@konce-pt/react 0.8.1 → 0.8.3

package/dist/datepicker/llms.txt

@@ -0,0 +1,74 @@
+# KptDatepicker (@konce-pt/react)
+
+Picking a date and time with a custom calendar. The granularity comes from `selectionMode`.
+Import: `import { KptDatepicker } from '@konce-pt/react';`
+
+## DOM
+    <div class="kpt-datepicker-host">
+      <div class="kpt-datepicker" role="button" tabindex="0">
+        <span class="kpt-datepicker__value">06.09.2026</span>
+        <span class="kpt-datepicker__spacer"></span>
+        <button class="kpt-datepicker__clear">…</button>
+        <span class="kpt-icon-host kpt-datepicker__icon">…</span>
+      </div>
+    </div>
+    <!-- in a portal: <div class="kpt-calendar">…</div> -->
+
+## Props
+- `value` / `defaultValue` / `onValueChange` — the value as a string; its format follows the mode:
+  'YYYY-MM-DD' / 'YYYY-MM' / 'YYYY' / 'MM' / 'YYYY-MM-DDTHH:mm' / 'HH:mm'
+- `selectionMode`: `'date'` (default) | `'monthYear'` | `'year'` | `'month'` | `'datetime'` | `'time'`
+- `startView`: `'day' | 'month' | 'year' | 'decade' | null` — the level the panel opens at; `null`
+  means the level where the mode commits. It is never lowered below that level, so
+  `startView="day"` in 'year' mode is raised to 'year'.
+- `minDate`, `maxDate`: 'YYYY-MM-DD' strings
+- `monthDisplay`: `'long'` (default) | `'number'`; `displayFormat`: `'pl'` (default) | `'iso'`
+- `hourFormat`: 12 | 24 (default 24) — the dial; the stored value is always 24h
+- `minuteStep`: number (default 1) — minute snapping on the dial
+- `open` / `onOpenChange` — the panel state, so it can be opened from outside
+- `placeholder`, `ariaLabel`, `disabled`, `invalid`, `touched`, `onTouch()`
+- `className`, `ref` and every other `<div>` prop go to the host
+
+## The view stack
+The header is always `‹ title ›`: the arrows page the current level, the title goes one level up.
+
+    day      ‹  [June]  [1979]  ›   arrows ±1 month;  the chips → months / years
+    month    ‹      [1979]      ›   arrows ±1 year;   the chip  → years
+    year     ‹  [1970 – 1979]   ›   arrows ±10 years; the chip  → decades
+    decade   ‹   1920 – 2039    ›   arrows ±120 years; the top of the stack
+
+Clicking a cell above the committing level drills down; on that level it sets the value and closes
+the panel. An arrow dims when the whole neighbouring page falls outside `minDate`/`maxDate`.
+
+## The logic lives in a package, the component only renders
+Every grid, bound and format comes from `@konce-pt/datetime` — pure functions with their own tests.
+The component holds nothing but React state: the page, the level, the time buffer.
+
+## The panel is set up on open, not on click
+The state is initialised in an effect keyed on `open`, because the panel can also be opened from
+outside through the `open` prop. The effect deliberately depends on `open` alone: a value changing
+while the panel is open must not reset the view under the user's fingers.
+
+## Requires
+`@konce-pt/styles/components` for the calendar styles. No CDK — the panel rides the internal
+overlay primitive.
+
+## Examples
+    <KptDatepicker value={date} onValueChange={setDate} />
+    <KptDatepicker startView="decade" minDate="1920-01-01" maxDate="2029-12-31" value={birth} onValueChange={setBirth} />
+    <KptDatepicker selectionMode="monthYear" value={period} onValueChange={setPeriod} />
+    <KptDatepicker selectionMode="datetime" hourFormat={12} value={at} onValueChange={setAt} />
+    <KptDatepicker selectionMode="time" value={alarm} onValueChange={setAlarm} />
+
+## i18n
+Weekday and month names come from `Intl` for the active locale, not from the dictionary. The
+navigation labels and "Done" come from the `datepicker` and `common` namespaces; `locale` and
+`dictionary` override them per instance.
+
+## Tokens
+`--kpt-form-field-{bg,text,border,border-focus,border-error,radius}`; the panel
+`--kpt-color-surface-raised`, the selection `--kpt-color-primary`.
+
+## Accessibility
+The trigger is `role="button"` with `tabindex="0"` and Enter; every cell is a real `<button>` with
+`aria-pressed`; `ariaLabel` names the field when no `<label for>` describes it.

package/dist/dialog/llms.txt

@@ -0,0 +1,51 @@
+# KptDialog (@konce-pt/react)
+
+A modal window on a native `<dialog>` — the focus trap, Escape and the backdrop come from the
+platform, not from our code. Import: `import { KptDialog } from '@konce-pt/react';`
+
+## DOM
+    <dialog class="kpt-dialog">
+      <div class="kpt-dialog__header">
+        <h2 class="kpt-dialog__title">Delete record?</h2>
+        <button class="kpt-dialog__close" type="button" aria-label="Close">…</button>
+      </div>
+      <div class="kpt-dialog__body">…children…</div>
+      <div kptdialogfooter="">…footer…</div>
+    </dialog>
+
+## Props
+- `open`: boolean, `onOpenChange(open)` — the dialog is always controlled; the browser can close it
+  on its own (Escape, the `close` event), and the state has to follow
+- `header`: string — the title; with no header there is no header row and no × button
+- `dismissible`: boolean (default true) — allows Escape and shows ×
+- `className`, `ref` and every other `<dialog>` prop go to the dialog
+
+## Sub-components
+- `KptDialog.Footer` — lifted below the body; carries the `kptdialogfooter` attribute the shared
+  SCSS targets.
+
+## An overlay inside a modal
+`showModal()` lifts the dialog into the browser's TOP LAYER, which sits above the whole document —
+no `z-index` beats it. A `KptSelect` or `KptMenu` panel portalled to `document.body` would open
+INVISIBLE, hidden behind the modal backdrop. While it is open, `KptDialog` therefore makes itself
+the overlay container (through `KptOverlayContainerContext`), so those panels portal INSIDE the
+`<dialog>`. The Angular port solves the same problem by moving the CDK overlay container into the
+dialog; the mechanism differs, the result does not.
+
+## Examples
+    <KptDialog open={open} onOpenChange={setOpen} header="Delete record?">
+      This action cannot be undone.
+      <KptDialog.Footer>
+        <KptButton variant="text" onClick={() => setOpen(false)}>Cancel</KptButton>
+        <KptButton variant="danger" onClick={remove}>Delete</KptButton>
+      </KptDialog.Footer>
+    </KptDialog>
+
+## Tokens
+`--kpt-color-surface-raised`, `--kpt-color-border`, `--kpt-radius-lg`, `--kpt-elevation-4`,
+`--kpt-color-overlay-scrim` (the `::backdrop`).
+
+## Accessibility
+A native `<dialog>` opened with `showModal()`: focus moves inside and is trapped, the rest of the
+page becomes inert, and Escape closes it — all from the browser. With `dismissible={false}` the
+`cancel` event is prevented, so Escape stops working; give the user another way out.

package/dist/divider/llms.txt

@@ -0,0 +1,28 @@
+# KptDivider (@konce-pt/react)
+
+A separator — a horizontal or vertical line. Colour from `--kpt-color-border`.
+Import: `import { KptDivider } from '@konce-pt/react';`
+
+## DOM
+    <div class="kpt-divider" role="separator" aria-orientation="horizontal" data-orientation="horizontal"></div>
+
+## Props
+- `orientation`: 'horizontal' | 'vertical' (default 'horizontal')
+- `inset`: boolean — an indent from the container edges
+- `className`, `ref` and every other `<div>` prop go to the divider
+
+## Vertical needs a flex parent
+The vertical variant stretches to the height of its container, so it only makes sense inside a
+flex row — on its own it has nothing to measure against and collapses to nothing.
+
+## Examples
+    <KptDivider />
+    <KptDivider inset />
+    <div style={{ display: 'flex' }}>A<KptDivider orientation="vertical" />B</div>
+
+## Tokens
+`--kpt-color-border`, `--kpt-space-*` for the inset.
+
+## Accessibility
+`role="separator"` with `aria-orientation`, so a screen reader announces the break instead of
+silently skipping a decorative line.

package/dist/drawer/llms.txt

@@ -0,0 +1,47 @@
+# KptDrawer (@konce-pt/react)
+
+A slide-out panel (drawer / off-canvas), independent of the app shell.
+Import: `import { KptDrawer } from '@konce-pt/react';`
+
+## DOM
+    <div class="kpt-drawer-host">
+      <div class="kpt-drawer__backdrop is-open"></div>
+      <aside class="kpt-drawer__panel is-open" data-position="right" role="dialog" aria-modal="true" tabindex="-1">
+        <div class="kpt-drawer__header">
+          <span class="kpt-drawer__title">Filters</span>
+          <button class="kpt-drawer__close" type="button" aria-label="Close">…</button>
+        </div>
+        <div class="kpt-drawer__body">…children…</div>
+      </aside>
+    </div>
+
+## Props
+- `open`: boolean, `onOpenChange(open)` — controlled
+- `position`: 'left' | 'right' | 'top' | 'bottom' (default 'left')
+- `header`: string
+- `dismissible`: boolean (default true) — shows × and lets Escape close it
+- `closeOnBackdrop`: boolean (default true)
+- `className`, `ref` and every other `<div>` prop go to the host
+
+## Always in the DOM
+The panel and the backdrop are always rendered; only the `is-open` class decides what is visible.
+That is what makes the slide animatable — mounting the panel on open would give the transition
+nothing to animate from.
+
+## Not a native modal
+Unlike `KptDialog` this is a plain `<aside role="dialog" aria-modal="true">`, so the browser does
+not trap focus and does not make the rest of the page inert. Escape works while the focus is inside
+the panel. For a hard modal reach for `KptDialog`.
+
+## Examples
+    <KptDrawer open={open} onOpenChange={setOpen} position="right" header="Filters">
+      Panel content…
+    </KptDrawer>
+
+## Tokens
+`--kpt-color-surface-raised`, `--kpt-color-border`, `--kpt-elevation-3`,
+`--kpt-color-overlay-scrim`, `--kpt-motion-duration-base`, `--kpt-z-overlay`.
+
+## Accessibility
+`role="dialog"` with `aria-modal="true"` and `tabindex="-1"`, so the panel can take focus. The close
+button gets its label from `common.close` in the dictionary.

package/dist/empty/llms.txt

@@ -0,0 +1,35 @@
+# KptEmpty (@konce-pt/react)
+
+An empty state — an icon, a title, a description and optional actions.
+Import: `import { KptEmpty } from '@konce-pt/react';`
+
+## DOM
+    <div class="kpt-empty-host">
+      <div class="kpt-empty">
+        <div class="kpt-empty__icon">…icon…</div>
+        <p class="kpt-empty__title">No results</p>
+        <p class="kpt-empty__desc">Adjust your search criteria.</p>
+        <div class="kpt-empty__actions">…children…</div>
+      </div>
+    </div>
+
+## Props
+- `icon`: string | null (default 'info-circle') — a registry icon name; `null` hides it
+- `title`: string, `description`: string — each row disappears when its text is empty
+- `children` — the actions under the description
+- `className`, `ref` and every other `<div>` prop go to the host
+
+## Examples
+    <KptEmpty icon="search" title="No results" description="Adjust your search criteria.">
+      <KptButton variant="outline">Clear filters</KptButton>
+    </KptEmpty>
+
+    <KptEmpty icon={null} title="Nothing here yet" />
+
+## Tokens
+`--kpt-color-on-surface-muted` (the description), `--kpt-space-*`.
+
+## Accessibility
+A plain container with no role of its own — the title is a `<p>`, not a heading, so it does not
+break the heading outline of the page. Where the empty state IS the heading of its section, render
+your own `<h2>` in the children instead.

package/dist/fab/llms.txt

@@ -0,0 +1,37 @@
+# KptFab (@konce-pt/react)
+
+A floating action button — round and raised. `extended` turns it into a pill with text.
+Import: `import { KptFab } from '@konce-pt/react';`
+
+## DOM
+    <span class="kpt-fab-host">
+      <button class="kpt-fab" type="button" data-variant="filled" data-size="md" aria-label="Add">…icon…</button>
+    </span>
+
+## Props
+- `variant`: 'filled' | 'tonal' (default 'filled')
+- `size`: 'md' | 'mini' (default 'md')
+- `extended`: boolean — a pill with text next to the icon
+- `hostProps` — props for the `.kpt-fab-host` wrapper
+- `className`, `ref` and every other `<button>` prop go to the inner `<button>`
+
+## The label depends on the variant
+In the round variant `aria-label` is essential — the button has no text. In `extended` the content
+already is the label, so `aria-label` is dropped there rather than passed through: two names on one
+control make a screen reader announce the wrong one.
+
+## Placement is yours
+The component does not position itself. It is a button, not a layout — put it in a container that
+pins it wherever the design wants (usually `position: fixed` in a corner).
+
+## Examples
+    <KptFab aria-label="Add"><KptIcon name="plus" /></KptFab>
+    <KptFab extended><KptIcon name="plus" /> New</KptFab>
+    <KptFab variant="tonal" size="mini" aria-label="Edit"><KptIcon name="copy" /></KptFab>
+
+## Tokens
+`--kpt-color-primary` / `--kpt-color-on-primary` (filled), `--kpt-color-muted` /
+`--kpt-color-on-muted` (tonal), `--kpt-elevation-3`, `--kpt-radius-full`.
+
+## Accessibility
+A native `<button>`; in the round variant give it `aria-label`, in `extended` the text does the job.

package/dist/fieldset/llms.txt

@@ -0,0 +1,43 @@
+# KptFieldset (@konce-pt/react)
+
+A group of fields with a legend, optionally collapsible.
+Import: `import { KptFieldset } from '@konce-pt/react';`
+
+## DOM
+    <div class="kpt-fieldset-host" style="--kpt-anim-duration:500ms">
+      <fieldset class="kpt-fieldset">
+        <legend class="kpt-fieldset__legend">
+          <button class="kpt-fieldset__toggle" aria-expanded="true">…<span>Personal data</span></button>
+        </legend>
+        <div class="kpt-fieldset__collapse is-open">
+          <div class="kpt-fieldset__collapse-inner"><div class="kpt-fieldset__body">…</div></div>
+        </div>
+      </fieldset>
+    </div>
+
+## Props
+- `legend`: string
+- `toggleable`: boolean — turns the legend into a collapse button
+- `collapsed` / `defaultCollapsed` / `onCollapsedChange`
+- `animated`: boolean (default true), `animationDuration`: ms (default 500)
+- `className`, `ref` and every other `<div>` prop go to the host
+
+## Collapsing without measuring
+The transition runs on `grid-template-rows: 0fr → 1fr`, so it animates to the content's natural
+height with no JS measurement and no height cached at mount — content that grows later still
+collapses correctly.
+
+## The real fieldset stays
+The markup is a native `<fieldset>` + `<legend>`, so the grouping is real for assistive tech;
+the collapse only wraps the body, never the legend.
+
+## Examples
+    <KptFieldset legend="Personal data" toggleable>…</KptFieldset>
+    <KptFieldset legend="Advanced" toggleable collapsed={closed} onCollapsedChange={setClosed}>…</KptFieldset>
+
+## Tokens
+Border `--kpt-color-border`, radius `--kpt-radius-md`, padding `--kpt-space-4`.
+
+## Accessibility
+The toggle carries `aria-expanded`; the collapsed body gets `inert` and `aria-hidden`, so it is
+out of the tab order and out of the accessibility tree.

package/dist/file-upload/llms.txt

@@ -0,0 +1,48 @@
+# KptFileUpload (@konce-pt/react)
+
+File upload: a zone that takes a click and a drop, plus the list of chosen files. The value is a
+`File[]`.
+Import: `import { KptFileUpload } from '@konce-pt/react';`
+
+## DOM
+    <div class="kpt-file-upload-host">
+      <div class="kpt-file-upload__zone is-dragover">
+        <input type="file" hidden>
+        <span class="kpt-icon-host kpt-file-upload__icon">…</span>
+        <div class="kpt-file-upload__text"><strong>Click</strong> or drag files here</div>
+        <div class="kpt-file-upload__hint">image/*</div>
+      </div>
+      <ul class="kpt-file-upload__list">
+        <li class="kpt-file-upload__file">…name, size, remove…</li>
+      </ul>
+    </div>
+
+## Props
+- `value` / `defaultValue` / `onValueChange` — the `File[]`
+- `accept`: string (e.g. `'image/*'`) — the native picker filter, also shown under the zone
+- `multiple`: boolean — off, only the first file is kept
+- `disabled`, `invalid`, `touched`, `onTouch()`
+- `className`, `ref` and every other `<div>` prop go to the host
+
+## The input is cleared after every pick
+`event.target.value = ''` after reading the files, otherwise picking the same file twice in a row
+would fire no `change` and the second pick would be silently lost.
+
+## The hint carries markup
+`fileUpload.hint` holds a `<strong>`, so it is rendered with `dangerouslySetInnerHTML` — the text
+comes from the dictionary (ours or the app's), never from user input.
+
+## Examples
+    <KptFileUpload value={files} onValueChange={setFiles} accept="image/*" multiple />
+    <KptFileUpload value={files} onValueChange={setFiles} />
+
+## i18n
+The zone hint and the remove label come from the `fileUpload` namespace; `locale` and `dictionary`
+override them per instance.
+
+## Tokens
+The zone `--kpt-form-field-border` (dashed), the dragover state `--kpt-color-primary`.
+
+## Accessibility
+The remove button is labelled from the dictionary; the file input stays a real `<input type="file">`,
+so the system picker and its keyboard path are untouched.

package/dist/form-field/llms.txt

@@ -0,0 +1,55 @@
+# KptFormField (@konce-pt/react)
+
+A field container: label, hint, error message and the required flag around any control.
+Import: `import { KptFormField } from '@konce-pt/react';`
+
+## DOM
+    <div class="kpt-form-field-host">
+      <div class="kpt-form-field kpt-form-field--fixed">
+        <div class="kpt-form-field__box is-filled">
+          <label class="kpt-form-field__label" for="…">E-mail<span class="kpt-form-field__required">*</span></label>
+          <div class="kpt-form-field__control">…control…</div>
+        </div>
+        <p class="kpt-form-field__message kpt-form-field__message--hint">Company e-mail</p>
+      </div>
+    </div>
+
+## Props
+- `label`: string — the label text
+- `hint`: string — a hint under the control, hidden while there is an error
+- `error`: string | null — when non-empty the field is marked invalid
+- `required`: boolean — an asterisk next to the label
+- `controlId`: string — empty means the wrapper generates one and hands it to the control
+- `labelType`: 'fixed' | 'over' | 'in' | 'on' (default 'fixed')
+- `className`, `ref` and every other `<div>` prop go to the host
+
+## Label wiring
+The wrapper generates a control id and publishes it through context, so `<KptInput>` inside needs
+no configuration — `label[for]` and `input[id]` always match. Pass `controlId` to take over.
+
+## Float labels
+`labelType` other than `fixed` turns on the floating label with an animated transition: `over`
+(above the border), `in` (top inside the field), `on` (on the border, notch). The label floats on
+focus (CSS `:focus-within`) or when the field is filled — no placeholder required.
+
+Filled state is read from the projected `input`/`textarea` on `input`/`change` and from the initial
+value, so it works for controlled and uncontrolled fields alike. A control with no native field
+reports it with `useKptFormFieldFilled(filled)`.
+
+## Examples
+    <KptFormField label="E-mail" hint="Company e-mail" error={err} required>
+      <KptInput type="email" name="email" placeholder="jan@firma.pl" />
+    </KptFormField>
+
+    <KptFormField label="Over Label" labelType="over">
+      <KptInput value={over} onValueChange={setOver} />
+    </KptFormField>
+
+## Tokens
+`--kpt-form-field-{label,hint,error,border,border-focus,border-error,radius}` and
+`--kpt-color-danger` for the required asterisk.
+
+## Accessibility
+The error message carries `role="alert"`, so a screen reader announces it as it appears. The
+asterisk is `aria-hidden` — the required state belongs on the control (`aria-required`), not on
+decoration.

package/dist/galleria/galleria.d.ts

@@ -7,7 +7,7 @@ export interface KptGalleriaItem {
     alt?: string;
 }
 export interface KptGalleriaProps extends Omit<ComponentPropsWithRef<'div'>, 'onChange'>, KptI18nOverrides {
-    items?: KptGalleriaItem[];
+    items?: readonly KptGalleriaItem[];
     activeIndex?: number;
     defaultActiveIndex?: number;
     onActiveIndexChange?: (index: number) => void;

package/dist/galleria/llms.txt

@@ -0,0 +1,46 @@
+# KptGalleria (@konce-pt/react)
+
+A large image preview with a thumbnail strip and navigation.
+Import: `import { KptGalleria, type KptGalleriaItem } from '@konce-pt/react';`
+
+## DOM
+    <div class="kpt-galleria-host">
+      <div class="kpt-galleria">
+        <div class="kpt-galleria__stage">
+          <button class="kpt-galleria__nav kpt-galleria__nav--prev">…</button>
+          <img class="kpt-galleria__image" src="…" alt="…">
+          <button class="kpt-galleria__nav kpt-galleria__nav--next">…</button>
+        </div>
+        <div class="kpt-galleria__thumbs">
+          <button class="kpt-galleria__thumb is-active"><img src="…"></button>…
+        </div>
+      </div>
+    </div>
+
+## Props
+- `items`: `KptGalleriaItem[]` — `{ src, thumbnail?, alt? }`
+- `activeIndex` / `defaultActiveIndex` / `onActiveIndexChange`
+- `showThumbnails`: boolean (default true)
+- `className`, `ref` and every other `<div>` prop go to the host
+
+## The thumbnail is optional
+Without `thumbnail` the strip shows the scaled-down main image, so a gallery works with a single
+URL per item; supply separate thumbnails when the originals are heavy.
+
+## An empty list renders the frame
+`items[active]` falling outside the array renders no image rather than throwing, so a gallery whose
+data is still loading shows the stage and the disabled arrows instead of crashing.
+
+## Examples
+    <KptGalleria items={photos} />
+    <KptGalleria items={photos} activeIndex={index} onActiveIndexChange={setIndex} showThumbnails={false} />
+
+## i18n
+The arrows use `common.previous` / `common.next`, the thumbnails `galleria.image` (`{index}`).
+
+## Tokens
+The stage `--kpt-color-muted`, the active thumbnail `--kpt-color-primary`.
+
+## Accessibility
+Each thumbnail is a labelled button, and the arrows go dark at the ends; `alt` comes from the item,
+so a photo without a description does not get a made-up one.

package/dist/grid/llms.txt

@@ -0,0 +1,110 @@
+# KptGrid / KptCol / KptFlex (@konce-pt/react/grid)
+
+React ergonomics over the `@konce-pt/grid` stylesheet. The components set nothing but inline custom
+properties — they neither add nor remove classes, and the layout is computed by the native CSS
+engine.
+
+Import: `import { KptGrid, KptCol, KptFlex } from '@konce-pt/react/grid';`
+Requires the stylesheet: `import '@konce-pt/grid';`
+
+## There are no directives in React
+The Angular port ships `kptGrid` / `kptCol` / `kptFlex` as attribute directives, which add nothing
+to the DOM. Here they are components, and `asChild` gives back the missing half: the props land on
+the element you were rendering anyway, so a column can be an `<li>`, an `<article>` or another
+component — no wrapper `<div>` in the middle of a grid.
+
+## Breakpoints (mobile-first)
+`sm` >= 640px, `md` >= 768px, `lg` >= 1024px, `xl` >= 1280px, `2xl` >= 1536px.
+A value applies from its breakpoint upward until the next one overrides it: `span={12} spanLg={5}`
+gives 12 on mobile, `sm` and `md`, and 5 only from `lg` up.
+
+## KptGrid
+Class `kpt-grid`. Renders a `<div>`, or the child with `asChild`.
+- `columns`: number — the column count (12 by default, from CSS). Variants: `columnsSm`,
+  `columnsMd`, `columnsLg`, `columnsXl`, `columns2xl`
+- `gap`: string — the gap on both axes, e.g. `'1.5rem'`, `'var(--kpt-space-6)'`
+- `gapX`, `gapY`: string — the gap on one axis, overriding `gap`
+- `container`: boolean — container query mode (see below)
+- `className`, `style`, `ref` and every other `<div>` prop pass through; your `style` wins over the
+  generated variables
+
+## KptCol
+No class of its own — only the variables.
+- `span`: number | string — the span, the mobile-first base; `'full'` means the whole width
+- `spanSm`, `spanMd`, `spanLg`, `spanXl`, `span2xl` — per-breakpoint overrides
+- `start`: number — the grid line the column starts at (1-based); this is how offsets are done
+- `order`: number — the visual order. It does not change the DOM: screen readers and keyboard
+  navigation follow the DOM, so do not use it to move interactive content around
+- `self`: string — `align-self` (`start`, `end`, `center`, `stretch`, `baseline`)
+
+## KptFlex
+Class `kpt-flex`. The same variables and breakpoints as the grid, in one dimension.
+- `direction`: 'row' | 'row-reverse' | 'column' | 'column-reverse' (+ `directionMd`, `directionLg`)
+- `wrap`: 'wrap' | 'nowrap' | 'wrap-reverse'
+- `justify`, `align` (+ `justifyMd`, `alignMd`): `start` | `end` | `center` | `stretch` |
+  `baseline` | `space-between` | `space-around` | `space-evenly`
+- `gap`, `gapX`, `gapY`: string
+- `container`: boolean
+
+Values with no matching prop are supplied with utility classes from `@konce-pt/grid`:
+`kpt-grow-1`, `kpt-shrink-0`, `kpt-order-first`, `kpt-self-end`, `kpt-gap-6`.
+
+## An undefined prop sets nothing
+A variable is written only when its prop has a value. Writing `--kpt-col: undefined` would override
+what a utility class or the stylesheet already provides, so the components skip it entirely — the
+same rule as the `?? null` in the Angular directives.
+
+## Container mode (`container`)
+The children's spans react to the width of THIS grid instead of the window — a card in a narrow
+sidebar lays itself out in a single column even though the viewport is wide.
+
+A CSS limitation, not a package one: `@container` queries the nearest ancestor container, so an
+element cannot query its own. What is responsive are the child's variables (span, start, order,
+self); the column count and the gaps still follow the viewport.
+
+## Examples
+    <KptGrid>
+      <KptCol span={12} spanSm={6} spanMd={4}>Card</KptCol>
+      <KptCol span={12} spanSm={6} spanMd={4}>Card</KptCol>
+      <KptCol span={12} spanMd={4}>Card</KptCol>
+    </KptGrid>
+
+    {/* 18 columns with no SCSS recompilation */}
+    <KptGrid columns={18} gap="1.5rem">
+      <KptCol span={18} spanLg={5}>Sidebar</KptCol>
+      <KptCol span={18} spanLg={13}>Content</KptCol>
+    </KptGrid>
+
+    {/* an offset and a reordering on mobile */}
+    <KptGrid>
+      <KptCol span={6} start={4}>start 4, span 6</KptCol>
+      <KptCol span={12} spanMd={6} className="kpt-order-first kpt-order-md-none">second in the DOM</KptCol>
+      <KptCol span={12} spanMd={6}>first in the DOM</KptCol>
+    </KptGrid>
+
+    {/* no extra elements: the list items are the columns */}
+    <KptGrid asChild>
+      <ul>
+        <KptCol asChild span={12} spanMd={6}><li>First</li></KptCol>
+        <KptCol asChild span={12} spanMd={6}><li>Second</li></KptCol>
+      </ul>
+    </KptGrid>
+
+    {/* flexbox */}
+    <KptFlex direction="column" directionMd="row" justify="space-between" align="center" gap="1rem">
+      <span>Left</span>
+      <span>Right</span>
+    </KptFlex>
+
+    {/* a form layout (a CSS preset, no props on the children) */}
+    <form className="kpt-grid kpt-form-grid">
+      <KptFormField label="First name"><KptInput name="firstName" /></KptFormField>
+      <KptFormField label="Notes" className="kpt-col-md-12"><KptInput name="notes" /></KptFormField>
+    </form>
+
+## Custom properties
+The grid: `--kpt-grid-columns`, `--kpt-gap`, `--kpt-gap-x`, `--kpt-gap-y`, `--kpt-justify`,
+`--kpt-align`, `--kpt-content`, `--kpt-flex-direction`, `--kpt-flex-wrap`.
+The child: `--kpt-col`, `--kpt-col-start`, `--kpt-order`, `--kpt-self`, `--kpt-flex`, `--kpt-grow`,
+`--kpt-shrink`.
+Each one has per-breakpoint variants: `--kpt-col` → `--kpt-col-md`.

package/dist/icon/icon-registry.d.ts

@@ -1,11 +1,14 @@
+import { type KptIconInput } from '@konce-pt/icons';
 /**
- * Rejestruje (lub nadpisuje) ikony: `{ nazwa: 'inner svg' }`.
+ * Rejestruje (lub nadpisuje) ikony. Przyjmuje listę definicji z subpathu Tablera
+ * (`[Rocket, LayoutDashboard]`), obiekt definicji (np. `import * as tabler`) albo
+ * mapę `{ nazwa: 'inner svg' }` — patrz [[KptIconInput]].
  *
  * Treść jest sanityzowana do allowlisty geometrii SVG — mimo to `registerKptIcons()` wolno
  * wołać wyłącznie z treścią kontrolowaną przez developera (build-time), nigdy bezpośrednio
  * z danych runtime/CMS/uploadu bez własnej walidacji domenowej wyżej w stosie.
  */
-export declare function registerKptIcons(next: Record<string, string>): void;
+export declare function registerKptIcons(next: KptIconInput): void;
 /** Zwraca wewnętrzny SVG ikony lub `undefined`. */
 export declare function getKptIcon(name: string): string | undefined;
 /** Czy ikona o tej nazwie jest w rejestrze. */

package/dist/icon/icon-registry.js

@@ -1,4 +1,4 @@
-import { KPT_ICONS, sanitizeSvgFragment } from '@konce-pt/icons';
+import { KPT_ICONS, sanitizeSvgFragment, toKptIconRecord } from '@konce-pt/icons';
 /*
  * Rejestr ikon dla `KptIcon`. Odpowiednik serwisu `KptIconRegistry` z portu Angulara,
  * ale jako moduł-singleton: ikony są globalne dla aplikacji, więc nie ma czego wstrzykiwać.
@@ -8,14 +8,16 @@ const icons = new Map(Object.entries(KPT_ICONS));
 const listeners = new Set();
 let version = 0;
 /**
- * Rejestruje (lub nadpisuje) ikony: `{ nazwa: 'inner svg' }`.
+ * Rejestruje (lub nadpisuje) ikony. Przyjmuje listę definicji z subpathu Tablera
+ * (`[Rocket, LayoutDashboard]`), obiekt definicji (np. `import * as tabler`) albo
+ * mapę `{ nazwa: 'inner svg' }` — patrz [[KptIconInput]].
  *
  * Treść jest sanityzowana do allowlisty geometrii SVG — mimo to `registerKptIcons()` wolno
  * wołać wyłącznie z treścią kontrolowaną przez developera (build-time), nigdy bezpośrednio
  * z danych runtime/CMS/uploadu bez własnej walidacji domenowej wyżej w stosie.
  */
 export function registerKptIcons(next) {
-    for (const [name, svg] of Object.entries(next)) {
+    for (const [name, svg] of Object.entries(toKptIconRecord(next))) {
         icons.set(name, sanitizeSvgFragment(svg));
     }
     version += 1;