quarc/core/pipes/README.md

Quarc Pipes

Zestaw podstawowych pipes dla frameworka Quarc, inspirowanych pipes z Angulara.

Instalacja

Pipes są dostępne w @quarc/core:

import { UpperCasePipe, DatePipe, JsonPipe } from '@quarc/core';

Użycie w komponentach

1. Zaimportuj pipe w komponencie

import { Component } from '@quarc/core';
import { UpperCasePipe } from '@quarc/core';

@Component({
    selector: 'app-example',
    template: '<div>{{ name | uppercase }}</div>',
    imports: [UpperCasePipe],
})
export class ExampleComponent {
    name = 'hello world';
}

2. Użyj w template

<!-- Prosty pipe -->
<div>{{ value | uppercase }}</div>

<!-- Pipe z argumentami -->
<div>{{ text | substr:0:10 }}</div>

<!-- Łańcuch pipes -->
<div>{{ name | lowercase | camelcase }}</div>

<!-- Kombinacja z operatorami -->
<div>{{ value || 'default' | uppercase }}</div>

Dostępne Pipes

UpperCasePipe

Konwertuje tekst na wielkie litery.

@Pipe({ name: 'uppercase' })

Przykłady:

{{ 'hello' | uppercase }}  <!-- HELLO -->
{{ name | uppercase }}      <!-- JOHN DOE -->

---

LowerCasePipe

Konwertuje tekst na małe litery.

@Pipe({ name: 'lowercase' })

Przykłady:

{{ 'HELLO' | lowercase }}  <!-- hello -->
{{ name | lowercase }}      <!-- john doe -->

---

JsonPipe

Serializuje obiekt do formatu JSON z wcięciami.

@Pipe({ name: 'json' })

Przykłady:

{{ user | json }}
<!--
{
  "name": "John",
  "age": 30
}
-->

{{ items | json }}
<!--
[
  "item1",
  "item2"
]
-->

---

CamelCasePipe

Konwertuje tekst do camelCase.

@Pipe({ name: 'camelcase' })

Przykłady:

{{ 'hello-world' | camelcase }}   <!-- helloWorld -->
{{ 'hello_world' | camelcase }}   <!-- helloWorld -->
{{ 'hello world' | camelcase }}   <!-- helloWorld -->
{{ 'HelloWorld' | camelcase }}    <!-- helloWorld -->

---

PascalCasePipe

Konwertuje tekst do PascalCase.

@Pipe({ name: 'pascalcase' })

Przykłady:

{{ 'hello-world' | pascalcase }}  <!-- HelloWorld -->
{{ 'hello_world' | pascalcase }}  <!-- HelloWorld -->
{{ 'hello world' | pascalcase }}  <!-- HelloWorld -->
{{ 'helloWorld' | pascalcase }}   <!-- HelloWorld -->

---

SnakeCasePipe

Konwertuje tekst do snake_case.

@Pipe({ name: 'snakecase' })

Przykłady:

{{ 'helloWorld' | snakecase }}    <!-- hello_world -->
{{ 'HelloWorld' | snakecase }}    <!-- hello_world -->
{{ 'hello-world' | snakecase }}   <!-- hello_world -->
{{ 'hello world' | snakecase }}   <!-- hello_world -->

---

KebabCasePipe

Konwertuje tekst do kebab-case.

@Pipe({ name: 'kebabcase' })

Przykłady:

{{ 'helloWorld' | kebabcase }}    <!-- hello-world -->
{{ 'HelloWorld' | kebabcase }}    <!-- hello-world -->
{{ 'hello_world' | kebabcase }}   <!-- hello-world -->
{{ 'hello world' | kebabcase }}   <!-- hello-world -->

---

SubstrPipe

Zwraca fragment tekstu.

@Pipe({ name: 'substr' })

Parametry:

• start: number - pozycja początkowa
• length?: number - długość fragmentu (opcjonalne)

Przykłady:

{{ 'hello world' | substr:0:5 }}   <!-- hello -->
{{ 'hello world' | substr:6 }}     <!-- world -->
{{ text | substr:0:10 }}           <!-- pierwsze 10 znaków -->

---

DatePipe

Formatuje daty.

@Pipe({ name: 'date' })

Parametry:

• format: string - format daty (domyślnie: 'medium')

Predefiniowane formaty:

Format	Przykład
short	1/15/24, 2:30 PM
medium	Jan 15, 2024, 2:30:45 PM
long	January 15, 2024 at 2:30:45 PM
full	Monday, January 15, 2024 at 2:30:45 PM
shortDate	1/15/24
mediumDate	Jan 15, 2024
longDate	January 15, 2024
fullDate	Monday, January 15, 2024
shortTime	2:30 PM
mediumTime	2:30:45 PM

Własne formaty:

Symbol	Znaczenie	Przykład
yyyy	Rok (4 cyfry)	2024
yy	Rok (2 cyfry)	24
MM	Miesiąc (2 cyfry)	01
M	Miesiąc (1-2 cyfry)	1
dd	Dzień (2 cyfry)	15
d	Dzień (1-2 cyfry)	15
HH	Godzina 24h (2 cyfry)	14
H	Godzina 24h (1-2 cyfry)	14
hh	Godzina 12h (2 cyfry)	02
h	Godzina 12h (1-2 cyfry)	2
mm	Minuty (2 cyfry)	30
m	Minuty (1-2 cyfry)	30
ss	Sekundy (2 cyfry)	45
s	Sekundy (1-2 cyfry)	45
a	AM/PM	PM

Przykłady:

{{ date | date }}                    <!-- Jan 15, 2024, 2:30:45 PM -->
{{ date | date:'short' }}            <!-- 1/15/24, 2:30 PM -->
{{ date | date:'yyyy-MM-dd' }}       <!-- 2024-01-15 -->
{{ date | date:'HH:mm:ss' }}         <!-- 14:30:45 -->
{{ date | date:'dd/MM/yyyy' }}       <!-- 15/01/2024 -->
{{ date | date:'h:mm a' }}           <!-- 2:30 PM -->

Łańcuchowanie Pipes

Możesz łączyć wiele pipes w łańcuch:

{{ name | lowercase | camelcase }}
{{ text | substr:0:20 | uppercase }}
{{ value | json | lowercase }}

Kombinacja z operatorami

Pipes działają poprawnie z operatorami logicznymi:

{{ value || 'default' | uppercase }}
{{ (name || 'Unknown') | pascalcase }}
{{ condition && value | lowercase }}

Tworzenie własnych Pipes

import { Pipe, PipeTransform } from '@quarc/core';

@Pipe({ name: 'reverse' })
export class ReversePipe implements PipeTransform {
    transform(value: string | null | undefined): string {
        if (value == null) return '';
        return String(value).split('').reverse().join('');
    }
}

Użycie:

@Component({
    selector: 'app-example',
    template: '<div>{{ text | reverse }}</div>',
    imports: [ReversePipe],
})
export class ExampleComponent {
    text = 'hello';  // Wyświetli: olleh
}

Testy

Wszystkie pipes są przetestowane. Uruchom testy:

cd /web/quarc/tests/unit
npx ts-node test-pipes.ts

Uwagi

• Wszystkie pipes obsługują wartości null i undefined zwracając pusty string
• DatePipe obsługuje obiekty Date, stringi i liczby (timestamp)
• Pipes są transformowane w czasie kompilacji na wywołania metod dla minimalnego rozmiaru bundle
• Pipes są pure (czyste) - wynik zależy tylko od argumentów wejściowych