tamga-ui 0.5.9 → 0.7.0

package/CHANGELOG.md

@@ -5,6 +5,162 @@ Versions follow [semver](https://semver.org/). Through `0.x`, breaking changes m
 
 > 🇹🇷 Türkçe için [tamga.org.tr/tr](https://tamga.org.tr/tr).
 
+## 0.7.0
+
+> A calendar can say no and carry the hour; a section can be told whether it is open; a label can
+> carry the user's colour; the settings page has a bottom; the image field can talk to a server.
+
+### Added
+
+- **`DatePicker` / `Calendar` `min` and `max`** (`DateISO`). Days outside the range are disabled
+  and announced as such, the arrow keys skip them, and a month button closes when the whole
+  month is out of reach. A product had fallen back to `<input type="date" min=…>` for "not before
+  today"; that field looks different in every browser and lets the user type a date the kit had
+  decided should only be picked.
+- **Calendar keyboard and grid semantics.** One day is in the tab order; the arrows move between
+  days (±1, ±7) across month edges, `Home`/`End` to the week's edges, `PageUp`/`PageDown` across
+  months; disabled days are skipped and the stop never lands on one (it follows the selected
+  day, else the first open day, and moves with an external `value`). `role="grid"` with rows
+  and `gridcell`s, every day named with its full date, `aria-selected` on the chosen day, native
+  `disabled` only.
+- **`DateTimePicker`.** Date plus time, picked not typed: a calendar and hour/minute selects
+  (AM/PM only in 12-hour locales; the words from `Intl`, else `labels.am`/`labels.pm`, never
+  the kit's own English). The value is `DateTimeISO`, an instant written with the offset of the
+  picker's `timeZone` at that instant, `2026-04-15T14:30:00+03:00`; send
+  `new Date(v).toISOString()` to the server. A separate component rather than a prop: the
+  value's shape is different, and an `onChange` whose type depends on a prop is a trap.
+  `labels` adds `hour`, `minute`, `period`.
+  - `timeZone` (IANA) on `Calendar`, `DatePicker` and `DateTimePicker`. Wall clock and instant
+    meet through `Intl`; "today", `min`/`max`, the field's text and the emitted offset all use
+    that zone, never the browser's. Give it explicitly in a server-rendered app. DST: an hour
+    inside a spring gap is not offered and a wall time in it is pushed forward; an autumn
+    ambiguous hour is written with the later, standard offset, while a value coming from
+    outside keeps its own offset, also when only its minute changes. Checked against an
+    independent oracle over the 2026 transitions of 418 zones.
+  - Every emitted value is inside `[min, max]`: day, hour, minute and AM/PM changes are clamped
+    to the nearest valid time and the selects follow; hours with no valid minute are not
+    offered. A stored minute off the `minuteStep` grid, or a stored value outside the range, is
+    shown as it is rather than rounded or hidden: the field never lies about a stored value.
+    The hour boxes stay locked until a day is picked, so an hour alone never emits today.
+    `minuteStep` below 1 reads as 1.
+  - `id` and `invalid` on both pickers, like `Input`. An invalid `timeZone` falls back to the
+    browser's and an unparseable `value` / `min` / `max` reads as empty, with a console warning
+    in development, instead of a `RangeError`.
+- **`Collapsible` controlled mode** · `open` + `onOpenChange(open)`. With `open` the product
+  holds the state and a click only reports; without it the section keeps its own, as before.
+  Both given, `open` wins and `defaultOpen` is ignored (React's contract). A product had rewritten
+  the row by hand because it needed to know when a row opened: it fetches on open.
+  - **`title` takes a node.** "Accessibility · /pricing" with the path faint; the accessible
+    name is `title` and `meta` together.
+  - **`note`** · a quiet line that stays visible while the section is closed, between head and
+    body, inside the same frame, bound to the head with `aria-describedby`: why a measurement
+    did not count, when it last ran.
+  - **`unmountOnClose`** · off by default (the body stays in the DOM, `hidden`); on, a heavy body
+    is not rendered while closed and `aria-controls` is omitted meanwhile.
+  - The caret's turn honours `prefers-reduced-motion`.
+- **`Tag` `swatch`** · the user's own colour as a small mark before the text, `aria-hidden`.
+  Hex only (`#rgb`, `#rgba`, `#rrggbb`, `#rrggbbaa`); anything else draws no mark, so user data
+  reaches `style` only as a validated value. This is the one **written** exception to Law 3
+  ("colour is for deviation and interaction"): the colour is the user's data, an identity mark,
+  never a ground or a text colour, never status. The ring around the mark derives from the ink
+  (from the page colour inside `look="solid"`), so a near-white or near-black choice stays
+  visible in both themes. Written into the physics page and `docs/gerekce/06`, so nobody deletes
+  it as a violation or cites it as a precedent. Without `swatch` the output is unchanged.
+  - **`ColorMark`** · the mark on its own, on the kit's `tamga-mark` family, for a clickable
+    suggestion inside a `Button`.
+  - **`ColorSwatches` `noneLabel`** · a "no colour" option; an empty value selects it instead
+    of lighting the custom box.
+- **`DangerZone` block** (`tamga-ui/blocks`) · the irreversible actions at the bottom of a
+  settings page. A title, an optional description and one or more action rows: an optional
+  name, one sentence, a `danger` button. `disabledReason` closes a row and shows the reason as
+  **visible text** bound to the button with `aria-describedby` · a disabled button is not a
+  reason, and a tooltip on one is invisible to most browsers, the keyboard and touch. `warning`
+  takes the kit's `Alert` when a precondition stopped the action; `busy` + `busyLabel` keep the
+  button named while it runs. The block never opens a confirm dialog: the click is the caller's,
+  the product builds `ConfirmDialog`. Edge and glyph tile in the critical tone, not the whole
+  card; the heading and the warning glyph say "danger" without colour. `data-action` sits on the
+  button, `data-key` on the row; every row takes `data-*`. A product had hand-written this zone
+  three ways on three pages.
+- **`ImageField` upload path** · `onUpload(file) => Promise<string | false>` and
+  `onRemove() => Promise<boolean | void>`. Given `onUpload`, the field no longer converts to a
+  data URL: it hands the `File` to the caller and carries the states. Waiting: the input and
+  every button lock, the button is named by `labels.uploading` / `labels.removing`. Failure: the
+  rejected reason (a string, an `Error`, or `{ message }`) under the field in a `role="alert"`
+  region, shown as it is, so map a raw network error to your own words first; an empty reason
+  shows the new `labels.errorUpload`. The chosen file and its preview stay, "confirm" retries.
+  Resolving `onUpload` with `false` keeps the kit silent, for a caller that already handled the
+  value or the error (a plan-wall dialog); any other non-string result warns in development,
+  because a forgotten `return` must never read as "uploaded". `onRemove` resolving `false` is
+  silent the same way. Success: the returned address goes to `onChange`, and a quiet inline
+  `role="status"` line (`labels.uploaded` / `labels.removed`). Both live regions are in the DOM
+  from the start, only their text changes. `confirm` previews the pick and waits for a click
+  (for a logo); the default uploads on pick (for an avatar). `accept` and `maxBytes` are
+  checked on both paths before anything else runs, an empty file is refused with
+  `errorUnreadable`; `disabled` + `lockedNote` show the reason as visible text wired to the
+  buttons with `aria-describedby`. The preview is an object URL, revoked on cancel, on a new
+  pick, on success, when `value` changes from outside, and on unmount; a result arriving after
+  unmount or after an outside `value` change is dropped, while the caller's own `onChange` with
+  the same result (a cache update inside `onUpload`) is not "outside". `maxEdge` is optional in
+  the type: not used with `onUpload`, and without either the image is kept at its own size.
+  `labels.empty` takes a `ReactNode`. The pre-existing synchronous path (no `onUpload`) renders
+  the same markup, locked by test; its only change is that a file outside `accept` is refused
+  before `prepareImage` (the input's own list said so already). A product had written this
+  field four times.
+- **`LogoTile` `surface`** · `"auto" | "light" | "dark"`, default `auto` (today's behaviour,
+  follows the page). `dark` draws the dark theme's ground even on a light page, for a logo drawn
+  for dark; `light` the reverse. Ground, edge and initial come as a fixed trio of tokens
+  (`--color-logo-ground/edge/ink-light|dark`), identical in both themes, so the tile reads the
+  same at night. Measured: initial 6.6:1 on light, 5.9:1 on dark; edge 3.9:1 on dark
+  (WCAG 1.4.11). A product that had been wrapping the tile in a local `.dark` class to get this
+  can drop the wrapper · note the ground differs by one step: the new dark surface is the dark
+  theme's **card** (`#16233a`), the old wrapper with `bg-page` gave the dark **page** (`#101a2c`).
+  Not pixel-identical; the card is what a tile sits on.
+- **`Select` `disabled`** · locks the trigger, and looks locked (sunk ground, dashed edge, faint
+  ink).
+- `check-item-hooks` also reads `actions` lists, and no longer mistakes `=>` for a closing
+  bracket (it was cutting item types short before their `Record<string, unknown>`).
+
+### Changed
+
+- The calendar's keyboard model: one tab stop and arrow keys instead of a tab stop on every day.
+  A `DatePicker` without `min`/`max` renders the same, but Tab now leaves the grid after one
+  stop; the arrows move inside it.
+
+### Fixed
+
+- **`DatePicker` `disabled`** left the clear and open buttons live: a locked date could be
+  cleared. Both buttons are disabled with the field.
+- **`Button` busy without `busyLabel`** had no accessible name: the label was `invisible` and
+  `aria-hidden`. The button's own text now stays in the tree as sr-only, as the docs claimed.
+- **Props tables on the docs site** · `ErrorState` lacked `onRetry` / `retryLabel` (a
+  parenthesised union was not read), `Button` lacked `busy` / `busyLabel` and `Input` `leading`
+  (an alias body was cut at its first `;`), and tables carried rows from types named inside a
+  prop (`AppShell` showed `NavEntry`'s fields). Only top-level intersections expand now, and a
+  row type such as `DangerAction` gets its own table.
+
+## 0.6.0
+
+> Sections fold; the one you are in never does.
+
+### Added
+
+- **`AppShell` section headers fold.** In the wide rail every section header is now a button:
+  click it and the section's entries slide shut; click again and they return. A customer with
+  eight sections asked for exactly this — the rail had become a wall. Three rules keep it honest:
+  the open page's section never folds (you can always read where you are), a route that lands
+  inside a folded section finds it open, and the narrow rail is untouched (nothing to fold when
+  there are no headers). New props: `collapsibleSections` (default `true`), `collapsedSections`
+  for a controlled rail, `onSectionToggle(section, open)`. Where the preference lives — browser,
+  account, device — is the product's call; the shell never writes storage.
+
+### Breaking
+
+- Section headers in the wide rail are `<button aria-expanded>` elements instead of `<p>`, and
+  each section's links now sit inside a `.tamga-rail-group-body` wrapper rather than directly
+  under `<nav>`. A selector written as `nav > .tamga-rail-link` or a test that read the header
+  as a paragraph needs updating; `data-nav` on every link is unchanged and is the supported hook.
+  Pass `collapsibleSections={false}` to keep plain headers (the wrapper stays either way).
+
 ## 0.5.9
 
 > The hook lands on the root, in every branch.

package/dist/blocks/danger-zone.d.ts

@@ -0,0 +1,54 @@
+import { type ReactNode } from "react";
+/**
+ * TEHLİKELİ BÖLGE · ayarlar sayfasının en altı, geri alınamayan eylemler.
+ *
+ * Üç ayar sayfası aynı bölgeyi üç ayrı biçimde elle yazıyordu; birinde kapalı
+ * düğmenin gerekçesi yalnız `title=` ipucundaydı. Blok onay penceresi AÇMAZ:
+ * tık çağırana gider, `ConfirmDialog`u ürün kurar · "adını yazdır" gibi
+ * kararlar onda kalır. Gerekçe: docs/gerekce/08-blok-ve-sablon.md
+ */
+export type DangerAction = {
+    key: string;
+    /**
+     * The row's title. Optional: when the button's label already names the action ("Delete the
+     * customer"), a title would repeat it, and three products had none. TR: Satırın başlığı.
+     * İsteğe bağlı: düğmenin metni eylemi zaten adlandırıyorsa ("Müşteriyi sil") başlık onu
+     * tekrarlardı, ve üç ürünün hiçbirinde yoktu.
+     */
+    title?: string;
+    /** One sentence saying what will happen. TR: Ne olacağını söyleyen tek cümle. */
+    description: string;
+    /** The button's text. TR: Düğmenin metni. */
+    label: string;
+    /** The click is the caller's; open your `ConfirmDialog` here. TR: Tık çağıranın; `ConfirmDialog`unu burada aç. */
+    onClick?: () => void;
+    /**
+     * Given, the row is closed and THIS SENTENCE is shown next to the button and bound to it with
+     * `aria-describedby`. A disabled button is not a reason; a tooltip on one is invisible to most
+     * browsers, to the keyboard and to touch. TR: Verilirse satır kapalı ve BU CÜMLE düğmenin
+     * yanında görünür, `aria-describedby` ile ona bağlı. Kapalı düğme bir gerekçe değildir; üstündeki
+     * ipucu çoğu tarayıcıda, klavyede ve dokunmatikte görünmez.
+     */
+    disabledReason?: string;
+    /** The action is running: the button shows a spinner and locks. TR: Eylem sürüyor: düğme spinner gösterir ve kilitlenir. */
+    busy?: boolean;
+    /** The button's accessible name while busy ("Deleting…"); without it the name would be empty. TR: Sürerken düğmenin erişilebilir adı ("Siliniyor…"); yoksa ad boş kalırdı. */
+    busyLabel?: string;
+    /**
+     * Shown under the row when a precondition stopped the action: the server said "do this first".
+     * Put the kit's `Alert` (`state="caution"`) here. TR: Bir önkoşul eylemi durdurduğunda satırın
+     * altında · sunucu "önce şunu yap" dedi. Kitin `Alert`ini (`state="caution"`) koy.
+     */
+    warning?: ReactNode;
+} & Record<string, unknown>;
+export declare function DangerZone({ title, description, actions, className, ...rest }: {
+    /** The zone's heading; names the region for assistive tech. TR: Bölgenin başlığı; yardımcı teknoloji için bölgeyi adlandırır. */
+    title: string;
+    /** One line under the heading: "Nothing here can be undone." TR: Başlığın altında tek satır: "Buradaki işlemler geri alınamaz." */
+    description?: string;
+    actions: readonly DangerAction[];
+    className?: string;
+    /** `data-*` hooks pass through. TR: `data-*` kancaları geçiyor. */
+    [k: `data-${string}`]: unknown;
+}): import("react").JSX.Element;
+//# sourceMappingURL=danger-zone.d.ts.map

package/dist/blocks/danger-zone.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"danger-zone.d.ts","sourceRoot":"","sources":["../../src/blocks/danger-zone.tsx"],"names":[],"mappings":"AAEA,OAAO,EAAS,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AAO9C;;;;;;;GAOG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB,GAAG,EAAE,MAAM,CAAC;IACZ;;;;;OAKG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,iFAAiF;IACjF,WAAW,EAAE,MAAM,CAAC;IACpB,6CAA6C;IAC7C,KAAK,EAAE,MAAM,CAAC;IACd,kHAAkH;IAClH,OAAO,CAAC,EAAE,MAAM,IAAI,CAAC;IACrB;;;;;;OAMG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,4HAA4H;IAC5H,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,8KAA8K;IAC9K,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,OAAO,CAAC,EAAE,SAAS,CAAC;CACrB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAE5B,wBAAgB,UAAU,CAAC,EACzB,KAAK,EACL,WAAW,EACX,OAAO,EACP,SAAS,EACT,GAAG,IAAI,EACR,EAAE;IACD,iIAAiI;IACjI,KAAK,EAAE,MAAM,CAAC;IACd,mIAAmI;IACnI,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,SAAS,YAAY,EAAE,CAAC;IACjC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,mEAAmE;IACnE,CAAC,CAAC,EAAE,QAAQ,MAAM,EAAE,GAAG,OAAO,CAAC;CAChC,+BAsDA"}

package/dist/blocks/danger-zone.js

@@ -0,0 +1,18 @@
+"use client";
+import { createElement as _createElement } from "react";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useId } from "react";
+import { Button } from "../components/button.js";
+import { Icon } from "../components/icon.js";
+import { Warning } from "../components/icons.js";
+import { cn } from "../lib/cn.js";
+import { dataProps } from "../lib/data-props.js";
+export function DangerZone({ title, description, actions, className, ...rest }) {
+    const id = useId();
+    return (_jsxs("section", { ...dataProps(rest), className: cn("tamga-danger-zone", className), "aria-labelledby": `${id}-b`, children: [_jsxs("div", { className: "tamga-danger-zone-head", children: [_jsx("span", { className: "tamga-danger-zone-tile", "aria-hidden": "true", children: _jsx(Icon, { icon: Warning, size: "sm", weight: "bold" }) }), _jsxs("div", { className: "min-w-0", children: [_jsx("h3", { id: `${id}-b`, className: "text-subhead font-semibold text-ink", children: title }), description ? _jsx("p", { className: "mt-1 text-small leading-relaxed text-ink-soft", children: description }) : null] })] }), _jsx("ul", { className: "tamga-danger-zone-list", children: actions.map(({ key, title: ad, description: ne, label, onClick, disabledReason, busy, busyLabel, warning, ...satir }, i) => {
+                    const gerekceId = `${id}-g${i}`;
+                    return (_createElement("li", { ...dataProps(satir), key: key, "data-key": key, "data-disabled": disabledReason ? "true" : undefined, className: "tamga-danger-zone-row" },
+                        _jsxs("div", { className: "flex flex-wrap items-start gap-4", children: [_jsxs("div", { className: "min-w-0 flex-1", children: [ad ? _jsx("p", { className: "text-body font-semibold text-ink", children: ad }) : null, _jsx("p", { className: ad ? "text-small leading-relaxed text-ink-soft" : "text-body leading-relaxed text-ink", children: ne }), disabledReason ? (_jsx("p", { id: gerekceId, className: "tamga-danger-zone-reason", "data-reason": true, children: disabledReason })) : null] }), _jsx(Button, { variant: "danger", size: "sm", "data-action": key, onClick: onClick, disabled: Boolean(disabledReason) || busy, busy: busy, busyLabel: busyLabel, "aria-describedby": disabledReason ? gerekceId : undefined, children: label })] }),
+                        warning ? _jsx("div", { className: "mt-3", children: warning }) : null));
+                }) })] }));
+}

package/dist/blocks/index.d.ts

@@ -8,4 +8,5 @@
 export { FilterBar, rangeStart, rangeEnd, type FilterBarLabels, type FilterBarProps, type FilterField, type FilterFieldKind, type FilterGroup, type FilterValues, } from "./filter-bar.js";
 export { SaveBar } from "./save-bar.js";
 export { CountRow } from "./count-row.js";
+export { DangerZone, type DangerAction } from "./danger-zone.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/blocks/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/blocks/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EACL,SAAS,EACT,UAAU,EACV,QAAQ,EACR,KAAK,eAAe,EACpB,KAAK,cAAc,EACnB,KAAK,WAAW,EAChB,KAAK,eAAe,EACpB,KAAK,WAAW,EAChB,KAAK,YAAY,GAClB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AACxC,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/blocks/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EACL,SAAS,EACT,UAAU,EACV,QAAQ,EACR,KAAK,eAAe,EACpB,KAAK,cAAc,EACnB,KAAK,WAAW,EAChB,KAAK,eAAe,EACpB,KAAK,WAAW,EAChB,KAAK,YAAY,GAClB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AACxC,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC1C,OAAO,EAAE,UAAU,EAAE,KAAK,YAAY,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/blocks/index.js

@@ -8,3 +8,4 @@
 export { FilterBar, rangeStart, rangeEnd, } from "./filter-bar.js";
 export { SaveBar } from "./save-bar.js";
 export { CountRow } from "./count-row.js";
+export { DangerZone } from "./danger-zone.js";

package/dist/components/appearance.d.ts

@@ -9,14 +9,23 @@ export type SwatchOption = {
  * Brand colour chosen from a few squares, or written by hand.
  * TR: Birkaç kareden seçilen ya da elle yazılan marka rengi.
  */
-export declare function ColorSwatches({ options, value, onChange, customLabel, custom, className, ...rest }: {
+export declare function ColorSwatches({ options, value, onChange, customLabel, custom, noneLabel, className, ...rest }: {
     options: readonly SwatchOption[];
+    /** The chosen hex; `""` means "no colour" when `noneLabel` is given. TR: Seçili hex; `noneLabel` verilmişse `""` "renk yok" demek. */
     value: string;
+    /** Fires with the hex, or `""` for the "no colour" box. TR: Hex ile ateşlenir; "renk yok" kutusu için `""`. */
     onChange: (hex: string) => void;
     /** Accessible name of the "my own colour" control. TR: "Kendi rengim" kontrolünün erişilebilir adı. */
     customLabel: string;
     /** Whether a free colour is offered at all. TR: Serbest rengin hiç sunulup sunulmadığı. */
     custom?: boolean;
+    /**
+     * Given, a first box means "no colour" and an empty `value` selects it. Without it an empty
+     * value lit the custom box, so an optional colour read as a choice. TR: Verilirse ilk kutu
+     * "renk yok" demek ve boş `value` onu seçer. Yokken boş değer "kendi rengim" kutusunu
+     * yakıyordu, isteğe bağlı bir renk bir seçim gibi okunuyordu.
+     */
+    noneLabel?: string;
     className?: string;
     /** `data-*` hooks pass through. TR: `data-*` kancaları geçiyor. */
     [k: `data-${string}`]: unknown;
@@ -88,27 +97,104 @@ export declare function RailCards({ value, onChange, labels, className, ...rest
  * offers reorder arrows with nothing to reorder.
  * TR: `FileUpload` DEĞİL: o bir GALERİ (çoklu seçim, sıralama okları, "kapak"
  * rozeti). Ürün fotoğrafları için doğru, tek bir logo için yanlış.
+ *
+ * Two paths, one field. Without `onUpload` the image is shrunk in the browser
+ * and a data URL goes to `onChange`. With `onUpload` the file goes to the
+ * caller and the field carries the states: waiting, failure, a quiet
+ * confirmation. TR: İki yol, tek alan. `onUpload` yokken görsel tarayıcıda
+ * küçültülür, data-URL `onChange`'e gider. `onUpload` verilince dosya çağırana
+ * gider; alan bekleme, hata ve sessiz onayı taşır.
+ *
+ * Gerekçe: docs/gerekce/01-form-ve-girdi.md
  */
-export declare function ImageField({ value, onChange, maxEdge, labels, preview, extra, className, ...rest }: {
+export declare function ImageField({ value, onChange, maxEdge, labels, preview, extra, onUpload, onRemove, confirm, accept, maxBytes, disabled, lockedNote, className, ...rest }: {
     value: string | null;
     onChange: (next: string | null) => void;
-    /** Longest edge of the stored image, in pixels. TR: Saklanan görselin en uzun kenarı, piksel. */
-    maxEdge: number;
+    /**
+     * Longest edge of the stored image, in pixels; the browser path shrinks to it, so give it
+     * there. Not used with `onUpload`: the server decides. TR: Saklanan görselin en uzun kenarı,
+     * piksel; tarayıcı yolu ona küçültür, orada ver. `onUpload` ile kullanılmaz: sunucu karar verir.
+     */
+    maxEdge?: number;
     labels: {
         /** "Logo", "Mark": used inside the buttons. TR: "Logo", "Amblem": düğmelerin içinde geçiyor. */
         name: string;
         upload: string;
         replace: string;
         remove: string;
-        empty: string;
+        /** The empty state's content: a sentence, or a node. TR: Boş durumun içeriği: bir cümle ya da bir düğüm. */
+        empty: ReactNode;
         errorType: string;
         errorSize: string;
         errorUnreadable: string;
+        /**
+         * Shown when `onUpload` or `onRemove` rejects without a message (an empty string, `undefined`);
+         * falls back to `errorUnreadable`. TR: `onUpload` ya da `onRemove` mesajsız reddedince (boş
+         * metin, `undefined`); yoksa `errorUnreadable`.
+         */
+        errorUpload?: string;
+        /** The button's name while `onUpload` runs; falls back to `upload`. TR: `onUpload` sürerken düğmenin adı; yoksa `upload`. */
+        uploading?: string;
+        /** The button's name while `onRemove` runs; falls back to `remove`. TR: `onRemove` sürerken düğmenin adı; yoksa `remove`. */
+        removing?: string;
+        /** The quiet line after a successful upload; omitted, nothing is said. TR: Başarılı yüklemeden sonraki sessiz satır; yoksa susar. */
+        uploaded?: string;
+        /** The quiet line after a successful removal. TR: Başarılı kaldırmadan sonraki sessiz satır. */
+        removed?: string;
+        /** The button that sends a previewed pick; falls back to `upload`. TR: Önizlenen seçimi gönderen düğme; yoksa `upload`. */
+        confirm?: string;
+        /** The button that drops a previewed pick; falls back to `remove`. TR: Önizlenen seçimi bırakan düğme; yoksa `remove`. */
+        cancel?: string;
     };
     /** The caller draws the preview: a logo is wide, a mark is square. TR: Önizlemeyi çağıran çiziyor: logo geniş, amblem kare. */
     preview: (src: string) => ReactNode;
     /** An extra control beside the buttons. TR: Düğmelerin yanına giren ek kontrol. */
     extra?: ReactNode;
+    /**
+     * Hands the chosen file to the caller instead of converting it. Resolve with the stored
+     * address: it goes to `onChange` and `labels.uploaded` is announced. Resolve with `false` when
+     * you handled the result yourself (a plan-wall dialog, your own `onChange`): the kit stays
+     * silent. Anything else is a bug and warns in development, because a forgotten `return` must
+     * not read as "uploaded". Reject with a string, an `Error` or `{ message }`: that text is shown
+     * under the field AS IT IS, so map a raw network error to your own words before rejecting; an
+     * empty reason shows `labels.errorUpload`. The file and its preview stay, "confirm" retries. A
+     * result that arrives after `value` changed from outside, or after unmount, is dropped. TR:
+     * Seçilen dosyayı dönüştürmek yerine çağırana verir. Saklanan adresle çözülür: `onChange`'e
+     * gider, `labels.uploaded` duyurulur. Sonucu kendin ele aldıysan `false` ile çöz: kit susar.
+     * Başka bir değer geliştirmede uyarır; unutulan bir `return` "yüklendi" sayılmaz. Metin, `Error`
+     * ya da `{ message }` ile reddedilirse metin alanın altında OLDUĞU GİBİ gösterilir, ağ hatasını
+     * reddetmeden önce kendi sözüne çevir; boş sebep `labels.errorUpload` gösterir. Dosya ve
+     * önizleme kalır, "confirm" yeniden dener. `value` dışarıdan değiştikten ya da bileşen
+     * kalktıktan sonra gelen sonuç atılır.
+     */
+    onUpload?: (file: File) => Promise<string | false>;
+    /**
+     * Awaited before `onChange(null)`; `false` keeps the kit silent (you handled it); a rejection
+     * shows under the field like `onUpload`'s. TR: `onChange(null)`'dan önce beklenir; `false` kiti
+     * susturur (sen ele aldın); red `onUpload`'daki gibi alanın altında.
+     */
+    onRemove?: () => Promise<boolean | void>;
+    /**
+     * Preview first, send on a click: for a logo, a chance to notice the wrong file. Off, the pick
+     * uploads at once (an avatar). TR: Önce önizle, tıklayınca gönder: logo için yanlış dosyayı fark
+     * etme şansı. Kapalıyken seçim hemen gider (avatar).
+     */
+    confirm?: boolean;
+    /**
+     * The input's accept list; the pick is checked against it on both paths, before `prepareImage`
+     * or `onUpload`. TR: Girdinin accept listesi; seçim iki yolda da `prepareImage` ya da
+     * `onUpload`'dan önce buna göre denetlenir.
+     */
+    accept?: string;
+    /** Refused on both paths with `errorSize`; 8 MB by default. TR: İki yolda da `errorSize` ile reddedilir; varsayılan 8 MB. */
+    maxBytes?: number;
+    disabled?: boolean;
+    /**
+     * Why the field is locked, as visible text under it and `aria-describedby` on the buttons; a
+     * tooltip hides from touch and keyboards. TR: Alanın neden kilitli olduğu, altında görünür
+     * metin ve düğmelerde `aria-describedby`; ipucu dokunmatikten ve klavyeden saklanır.
+     */
+    lockedNote?: string;
     className?: string;
     /** `data-*` hooks pass through. TR: `data-*` kancaları geçiyor. */
     [k: `data-${string}`]: unknown;

package/dist/components/appearance.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"appearance.d.ts","sourceRoot":"","sources":["../../src/components/appearance.tsx"],"names":[],"mappings":"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"}
+{"version":3,"file":"appearance.d.ts","sourceRoot":"","sources":["../../src/components/appearance.tsx"],"names":[],"mappings":"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"}

package/dist/components/appearance.js

@@ -1,22 +1,24 @@
 "use client";
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useId, useRef, useState } from "react";
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useId, useRef, useState } from "react";
 import { cn } from "../lib/cn.js";
 import { makePalette } from "../lib/palette.js";
 import { dataProps } from "../lib/data-props.js";
-import { IMAGE_ACCEPT, prepareImage } from "../lib/image.js";
+import { IMAGE_ACCEPT, RAW_LIMIT, prepareImage } from "../lib/image.js";
+import { uyar } from "../lib/uyar.js";
 import { Alert } from "./primitives.js";
 import { Button } from "./button.js";
 import { Icon } from "./icon.js";
-import { Check, Eyedropper } from "./icons.js";
+import { Check, Eyedropper, Close } from "./icons.js";
 /**
  * Brand colour chosen from a few squares, or written by hand.
  * TR: Birkaç kareden seçilen ya da elle yazılan marka rengi.
  */
-export function ColorSwatches({ options, value, onChange, customLabel, custom = true, className, ...rest }) {
+export function ColorSwatches({ options, value, onChange, customLabel, custom = true, noneLabel, className, ...rest }) {
     const secili = (hex) => hex.toLowerCase() === value.toLowerCase();
-    const hazirMi = options.some((o) => secili(o.hex));
-    return (_jsxs("span", { ...dataProps(rest), className: cn("flex flex-wrap items-center gap-3", className), children: [options.map(({ hex, label: etiket, ...rest }) => (_jsx("button", { ...rest, type: "button", className: "tamga-swatch", style: { background: hex, color: mürekkep(hex) }, "data-selected": secili(hex), "aria-pressed": secili(hex), "aria-label": etiket, title: etiket, onClick: () => onChange(hex), children: secili(hex) ? _jsx(Icon, { icon: Check, size: "base", weight: "bold" }) : null }, hex))), custom ? (_jsxs("label", { className: "tamga-swatch tamga-swatch-custom", "data-selected": !hazirMi, title: customLabel, style: hazirMi
+    const yokSecili = noneLabel !== undefined && value === "";
+    const hazirMi = yokSecili || options.some((o) => secili(o.hex));
+    return (_jsxs("span", { ...dataProps(rest), className: cn("flex flex-wrap items-center gap-3", className), children: [noneLabel !== undefined ? (_jsx("button", { type: "button", className: "tamga-swatch tamga-swatch-none", "data-selected": yokSecili, "aria-pressed": yokSecili, "aria-label": noneLabel, title: noneLabel, onClick: () => onChange(""), children: yokSecili ? _jsx(Icon, { icon: Check, size: "base", weight: "bold" }) : _jsx(Icon, { icon: Close, size: "base", weight: "bold" }) })) : null, options.map(({ hex, label: etiket, ...rest }) => (_jsx("button", { ...rest, type: "button", className: "tamga-swatch", style: { background: hex, color: mürekkep(hex) }, "data-selected": secili(hex), "aria-pressed": secili(hex), "aria-label": etiket, title: etiket, onClick: () => onChange(hex), children: secili(hex) ? _jsx(Icon, { icon: Check, size: "base", weight: "bold" }) : null }, hex))), custom ? (_jsxs("label", { className: "tamga-swatch tamga-swatch-custom", "data-selected": !hazirMi, title: customLabel, style: hazirMi
                     ? /* Hiçbir hazır renk seçili değilken kutu o rengi giyiyor;
                          seçiliyken damalı zemin "burada henüz bir renk yok" diyor. */
                         { background: DAMA }
@@ -117,29 +119,173 @@ export function RailCards({ value, onChange, labels, className, ...rest }) {
  * offers reorder arrows with nothing to reorder.
  * TR: `FileUpload` DEĞİL: o bir GALERİ (çoklu seçim, sıralama okları, "kapak"
  * rozeti). Ürün fotoğrafları için doğru, tek bir logo için yanlış.
+ *
+ * Two paths, one field. Without `onUpload` the image is shrunk in the browser
+ * and a data URL goes to `onChange`. With `onUpload` the file goes to the
+ * caller and the field carries the states: waiting, failure, a quiet
+ * confirmation. TR: İki yol, tek alan. `onUpload` yokken görsel tarayıcıda
+ * küçültülür, data-URL `onChange`'e gider. `onUpload` verilince dosya çağırana
+ * gider; alan bekleme, hata ve sessiz onayı taşır.
+ *
+ * Gerekçe: docs/gerekce/01-form-ve-girdi.md
  */
-export function ImageField({ value, onChange, maxEdge, labels, preview, extra, className, ...rest }) {
+export function ImageField({ value, onChange, maxEdge, labels, preview, extra, onUpload, onRemove, confirm = false, accept = IMAGE_ACCEPT, maxBytes = RAW_LIMIT, disabled = false, lockedNote, className, ...rest }) {
     const id = useId();
     const girdi = useRef(null);
     const [hata, setHata] = useState(null);
+    const [bekleyen, setBekleyen] = useState(null);
+    const [mesgul, setMesgul] = useState(null);
+    const [onay, setOnay] = useState(null);
+    /* Adres ref'te de: kalkışta son adresi bırakmak için state okunamıyor. İstek
+       sayacı, "canlı" bayrağı ve son değer bayat cevabı ayırıyor: kalkıştan ya da
+       dış değer değişiminden sonra gelen sonuç ne onChange'e gider ne ekrana. */
+    const adres = useRef(null);
+    const istek = useRef(0);
+    const canli = useRef(true);
+    const sonDeger = useRef(value);
+    sonDeger.current = value;
+    function birak() {
+        if (adres.current)
+            URL.revokeObjectURL(adres.current);
+        adres.current = null;
+        setBekleyen(null);
+    }
+    useEffect(() => {
+        canli.current = true;
+        return () => {
+            canli.current = false;
+            if (adres.current)
+                URL.revokeObjectURL(adres.current);
+            adres.current = null;
+        };
+    }, []);
+    /* Değer dışarıdan geldiyse bekleyen önizleme bayat kaldı. */
+    useEffect(() => {
+        if (value && adres.current)
+            birak();
+    }, [value]);
+    const kilit = disabled || mesgul !== null;
+    /* Dış değer değiştiyse sonuç bayat · ama çağıranın KENDİ güncellemesi değil:
+       onUpload içinde önbelleği sonuçla, onRemove içinde null ile güncelleyen bir
+       çağıran "yüklendi"yi yine duymalı. */
+    const bayat = (benim, baslangic, beklenen) => !canli.current ||
+        istek.current !== benim ||
+        (sonDeger.current !== baslangic && (beklenen === undefined || sonDeger.current !== beklenen));
+    function sifirla() {
+        /* GİRDİ SIFIRLANIYOR: aynı dosya ikinci kez seçilince `change` hiç
+           çıkmıyor, çünkü değer değişmiyor. Kullanıcı için bu "ikinci denemede
+           çalışmıyor" demek. */
+        if (girdi.current)
+            girdi.current.value = "";
+    }
     async function al(file) {
-        if (!file)
+        if (!file || kilit)
+            return;
+        sifirla();
+        setHata(null);
+        setOnay(null);
+        if (!kabul(file, accept))
+            return setHata(labels.errorType);
+        if (file.size === 0)
+            return setHata(labels.errorUnreadable);
+        if (file.size > maxBytes)
+            return setHata(labels.errorSize);
+        if (!onUpload) {
+            try {
+                onChange(await prepareImage(file, maxEdge ?? Infinity));
+            }
+            catch (e) {
+                const kod = e instanceof Error ? e.message : "unreadable";
+                setHata(kod === "type" ? labels.errorType : kod === "size" ? labels.errorSize : labels.errorUnreadable);
+            }
+            return;
+        }
+        birak();
+        const url = URL.createObjectURL(file);
+        adres.current = url;
+        setBekleyen({ file, url });
+        if (!confirm)
+            await gonder(file);
+    }
+    async function gonder(file) {
+        if (!onUpload || mesgul)
+            return;
+        const benim = ++istek.current;
+        const baslangic = sonDeger.current;
+        setHata(null);
+        setOnay(null);
+        setMesgul("upload");
+        try {
+            const sonuc = await onUpload(file);
+            if (bayat(benim, baslangic, typeof sonuc === "string" ? sonuc : undefined))
+                return;
+            if (typeof sonuc === "string") {
+                birak();
+                onChange(sonuc);
+                setOnay(labels.uploaded ?? null);
+            }
+            else if (sonuc !== false) {
+                uyar("ImageField: onUpload resolved with neither an address nor `false`; nothing was announced. Return the stored address, or `false` when you handled the result yourself.");
+            }
+        }
+        catch (e) {
+            if (bayat(benim, baslangic, undefined))
+                return;
+            setHata(metin(e, labels));
+        }
+        finally {
+            if (canli.current)
+                setMesgul(null);
+        }
+    }
+    async function kaldir() {
+        if (kilit)
             return;
         setHata(null);
+        setOnay(null);
+        if (!onRemove)
+            return onChange(null);
+        const benim = ++istek.current;
+        const baslangic = sonDeger.current;
+        setMesgul("remove");
         try {
-            onChange(await prepareImage(file, maxEdge));
+            const sonuc = await onRemove();
+            if (bayat(benim, baslangic, null) || sonuc === false)
+                return;
+            onChange(null);
+            setOnay(labels.removed ?? null);
         }
         catch (e) {
-            const kod = e instanceof Error ? e.message : "unreadable";
-            setHata(kod === "type" ? labels.errorType : kod === "size" ? labels.errorSize : labels.errorUnreadable);
+            if (bayat(benim, baslangic, undefined))
+                return;
+            setHata(metin(e, labels));
         }
         finally {
-            /* GİRDİ SIFIRLANIYOR: aynı dosya ikinci kez seçilince `change` hiç
-               çıkmıyor, çünkü değer değişmiyor. Kullanıcı için bu "ikinci denemede
-               çalışmıyor" demek. */
-            if (girdi.current)
-                girdi.current.value = "";
+            if (canli.current)
+                setMesgul(null);
         }
     }
-    return (_jsxs("div", { ...dataProps(rest), className: cn("flex flex-col gap-3", className), children: [_jsx("input", { ref: girdi, id: id, type: "file", accept: IMAGE_ACCEPT, className: "sr-only", onChange: (e) => al(e.target.files?.[0]) }), _jsxs("div", { className: "flex flex-wrap items-center gap-4", children: [_jsx("span", { className: "tamga-image-field", "data-empty": value ? undefined : "true", children: value ? preview(value) : labels.empty }), _jsxs("span", { className: "flex flex-wrap items-center gap-2", children: [_jsx(Button, { type: "button", onClick: () => girdi.current?.click(), children: value ? labels.replace : labels.upload }), extra, value ? (_jsx(Button, { type: "button", variant: "ghost", onClick: () => onChange(null), children: labels.remove })) : null] })] }), hata ? _jsx(Alert, { state: "danger", title: hata }) : null] }));
+    const gosterilen = bekleyen?.url ?? value;
+    const asenkron = Boolean(onUpload || onRemove);
+    const notKimligi = `${id}-kilit`;
+    const tarif = disabled && lockedNote ? notKimligi : undefined;
+    return (_jsxs("div", { ...dataProps(rest), className: cn("flex flex-col gap-3", className), children: [_jsx("input", { ref: girdi, id: id, type: "file", accept: accept, className: "sr-only", disabled: kilit || undefined, onChange: (e) => al(e.target.files?.[0]) }), _jsxs("div", { className: "flex flex-wrap items-center gap-4", children: [_jsx("span", { className: "tamga-image-field", "data-empty": gosterilen ? undefined : "true", children: gosterilen ? preview(gosterilen) : labels.empty }), _jsxs("span", { className: "flex flex-wrap items-center gap-2", children: [bekleyen ? (_jsxs(_Fragment, { children: [_jsx(Button, { type: "button", busy: mesgul === "upload", busyLabel: labels.uploading ?? labels.upload, disabled: kilit || undefined, "aria-describedby": tarif, onClick: () => gonder(bekleyen.file), children: labels.confirm ?? labels.upload }), _jsx(Button, { type: "button", variant: "ghost", disabled: kilit || undefined, onClick: birak, children: labels.cancel ?? labels.remove })] })) : (_jsx(Button, { type: "button", busy: mesgul === "upload", busyLabel: labels.uploading ?? labels.upload, disabled: kilit || undefined, "aria-describedby": tarif, onClick: () => girdi.current?.click(), children: value ? labels.replace : labels.upload })), extra, value && !bekleyen ? (_jsx(Button, { type: "button", variant: "ghost", busy: mesgul === "remove", busyLabel: labels.removing ?? labels.remove, disabled: kilit || undefined, "aria-describedby": tarif, onClick: kaldir, children: labels.remove })) : null] })] }), lockedNote && disabled ? (_jsx("p", { id: notKimligi, className: "text-small text-ink-faint", children: lockedNote })) : null, asenkron ? (_jsx("p", { role: "status", className: cn("text-small text-ink-faint", !onay && "sr-only"), children: onay })) : null, asenkron ? (_jsx("div", { role: "alert", className: cn(!hata && "sr-only"), children: hata ? _jsx(Alert, { state: "danger", title: hata }) : null })) : hata ? (_jsx(Alert, { state: "danger", title: hata })) : null] }));
+}
+/** `accept` listesine karşı ön denetim: MIME, `image/*` ve `.png` biçimleri. Boş liste her şeyi geçirir. */
+function kabul(file, accept) {
+    const liste = accept.split(",").map((s) => s.trim().toLowerCase()).filter(Boolean);
+    if (liste.length === 0)
+        return true;
+    const tur = file.type.toLowerCase();
+    const ad = file.name.toLowerCase();
+    return liste.some((k) => k.startsWith(".") ? ad.endsWith(k) : k.endsWith("/*") ? tur.startsWith(k.slice(0, -1)) : tur === k);
+}
+/** Çağıranın reddi: metin, `Error` ya da `{ message }` olduğu gibi; boşsa kitin genel sözü. */
+function metin(e, labels) {
+    const yedek = labels.errorUpload ?? labels.errorUnreadable;
+    if (typeof e === "string")
+        return e || yedek;
+    if (e && typeof e === "object" && "message" in e && typeof e.message === "string" && e.message)
+        return e.message;
+    return yedek;
 }