@box-kite/react 2.2.5 → 2.2.7

package/BOX_KITE_AI_CONTEXT.md

@@ -307,6 +307,19 @@ Any colour value takes a slash and a percentage:
 - A token the palette does not have, or a percentage outside 0–100, produces **no rule and no class
   name** — the same silence every unmatched value gets.
 
+**Two more families, `accent` and `base`, are what every built-in component is drawn in.** They start as
+copies of `indigo` and `gray`, so nothing changes until one is pointed somewhere. `Box.palette()` returns the
+`vars` record that does it, for an element and its subtree — a family by name, or a ramp of your own:
+
+```tsx
+<Box vars={Box.palette({ accent: 'orange', base: 'stone' })} />           // every Button inside is orange
+<Box vars={Box.palette({ accent: { 500: 'oklch(68% .19 42)' } })} />     // a step left out keeps its default
+<Box theme={{ dark: { vars: Box.palette({ accent: 'amber' }) } }} />     // nests like any vars
+```
+
+Write `accent-*`/`base-*` in your own components when they should follow a design, and a named family when the
+colour is the content (a status, a chart series). A class built from them reads `bgColor-accent-500`.
+
 ### Gradients, shadows and rings
 
 A gradient is a **value**, written as a record — so its stops are palette tokens, it takes the opacity
@@ -330,7 +343,10 @@ modifier, it is themed, and two elements asking for the same one share a class.
 - A stop is any colour value — a token, `blue-500/40`, a system colour, `var(--chart-1)` — or a
   `[colour, position]` pair. **Two stops minimum**, and the record is judged whole: one bad stop, one
   unknown key, two kinds at once, and the whole value emits no rule and no class name.
-- It writes `background-image`, so `bgGradient` and `bgImage` are the same property.
+- It writes `background-image`, so `bgGradient` and `bgImage` are the same property. `bgGradient` is declared
+  later and wins, so a variant or a design takes a gradient off with `bgGradient: 'none'`, never `bgImage: 'none'`.
+- `letterSpacing` is pixels as a number, and Tailwind's tracking names in `em` — `'tighter'` (-0.05em), `'tight'`,
+  `'normal'`, `'wide'`, `'wider'`, `'widest'` (0.1em) — which is what a display heading wants at every size.
 
 **Four shadows stack**, because each sets its own custom property and all four write one composed
 `box-shadow`. A ring and an elevation coexist instead of the last one winning:
@@ -1094,6 +1110,40 @@ const harbor = Box.createComponents({ button: { styles: { borderRadius: 0 } } },
 - **A Server Component cannot read the provider.** A client component under it can.
 - **Types for two designs that both name a component**: `interface ComponentsTypes extends MergeComponentsAndVariants<[typeof aurora, typeof harbor]> {}` (from `@box-kite/core/types`). Extending two `ExtractComponentsAndVariants` that disagree on `button` is an interface conflict.
 
+### Box.components(styles, { design }) — A Design Chosen in CSS
+
+A registry is chosen by React context, so a prerendered page can only switch to it after hydration — a flash, and a
+hydration mismatch if the client renders it first. A **named design** is chosen by an attribute instead: its styles are
+merged over the app's components and applied wherever an ancestor carries `data-design="<name>"`, so a stored choice
+written onto `<html>` before the first paint is the whole fix.
+
+```tsx
+Box.components({ button: { styles: { borderRadius: 2.5 } }, dialog: { styles: { borderRadius: 5, p: 7 } } }, { design: 'ember' });
+
+<Box.Theme
+  use="global"
+  design="classic"
+  designStorageKey="design"
+  globalStyles={{ dataAttr: { 'design=ember': { vars: Box.palette({ accent: 'orange', base: 'stone' }) } } }}
+>
+  <App />
+</Box.Theme>;
+
+const [design, setDesign] = Box.useDesign(); // setDesign(null) goes back to the design prop
+```
+
+- **Both designs are in the CSS.** A Box whose component a design changes carries the design's whole class list beside its
+  own, each rule one class more specific — so every state the app's design styles (a theme, a hover, a variant) is
+  outranked by the same state of the design. A component the design leaves alone costs nothing.
+- **To take something back off, write its `none`** (`shadow: 'none'`, `bgGradient: 'none'`): a design merges, it cannot delete a key.
+- **A design nested in another stops the outer one** — a `data-design="classic"` preview inside an Ember page is Classic.
+  The palette is `vars`, which inherit, so that wrapper declares its own `Box.palette()` too.
+- **Props still win**, and a Box under `<Box.Components value>` resolves against that registry and no named design.
+- `Box.Theme` writes `data-design` on `<html>` (`use="global"`) or on its wrapper, restores `designStorageKey` after
+  hydration without writing the default over a value a pre-paint script set, and pauses transitions for the switch.
+  `applyDesignToElement` is the framework-free half, in `@box-kite/core`.
+- **A part can `extends` too**: `trigger: { extends: 'button' }` or `'dialog.title'`. It used to be silently ignored.
+
 ---
 
 ## Extension System
@@ -2189,6 +2239,94 @@ Box.components({
 
 ---
 
+## Dates and times (`@box-kite/react/date` + the date components)
+
+```tsx
+import { format, toUtc, toLocal, toZone, toPlainDate, parse, add, today } from '@box-kite/react/date';
+import DateField from '@box-kite/react/components/dateField';
+import Calendar from '@box-kite/react/components/calendar';
+import DatePicker, { DateRangePicker } from '@box-kite/react/components/datePicker';
+import TimeZoneSelect from '@box-kite/react/components/timeZoneSelect';
+import DateTime, { DateProvider } from '@box-kite/react/components/dateTime';
+
+toUtc('2026-10-19T14:30', { from: 'Europe/Chisinau' }); // '2026-10-19T11:30:00Z'
+toLocal('2026-10-19T11:30:00Z'); // the reader's wall clock, with its offset
+format('2026-10-19', { locale: 'ro-MD', dateStyle: 'long' }); // '19 octombrie 2026'
+parse('03/04/2026', { locale: 'en-GB' }); // '2026-04-03'
+
+<DateField label="Due" name="due" />;
+<DatePicker type="datetime" zone="utc" label="Publish at" onValueChange={(value, { utc, local }) => schedule(utc)} />;
+<DateRangePicker label="Stay" startName="from" endName="to" />;
+<DateTime value={order.createdAt} />;
+```
+
+**Every value is an ISO string, and its shape is its kind** — never a `Date`, which is always a moment in
+the runtime's zone:
+
+| Kind       | Written as                                 | Means                                                     |
+| ---------- | ------------------------------------------ | --------------------------------------------------------- |
+| `date`     | `2026-10-19`                               | A day: no time, no zone, the same everywhere.             |
+| `time`     | `14:30:00` (`.sss` when there are any)     | A time of day.                                            |
+| `datetime` | `2026-10-19T14:30:00`                      | A wall clock with no zone — an alarm, a timetable.        |
+| `instant`  | `2026-10-19T14:30:00+03:00`, or `…Z` (UTC) | One moment, written as one zone sees it. Anything stored. |
+
+A zone is `'local'` (the reader), `'utc'`, `'system'` (the runtime), an IANA name or a fixed offset.
+**`'local'` on a server** is `configureDates({ timeZone })` or the nearest `<DateProvider timeZone>`;
+`systemZone()` is always the server's own. The browser writes its zone into a cookie with
+`document.cookie = zoneCookie()`, and a server reads it back with `readZoneCookie(request.headers.get('cookie'))`.
+
+| Function (`@box-kite/react/date`)                                               | What it does                                                                |
+| ------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
+| `toUtc(v, { from })` / `toLocal(v)` / `toZone(v, zone)`                         | The moment in UTC / on the reader's clock / on another zone's, with offset. |
+| `toPlainDate` / `toPlainTime` / `toPlainDateTime` / `toInstant`                 | `(v, { zone })` — the day, time or wall clock a value shows in `zone`.      |
+| `toDate` / `fromDate` / `toEpoch`                                               | The bridge to an API that insists on a `Date`.                              |
+| `combine(date, time, { zone })`                                                 | A date and a time: a date-time, or with `zone` the instant.                 |
+| `today(zone)` / `now(zone)` / `currentTime(zone)`                               | In the reader's zone unless told.                                           |
+| `format(v, { locale, zone, dateStyle, timeStyle, … })`                          | `Intl` options, never format tokens. `''` for a non-value.                  |
+| `formatRange` / `formatRelative` / `zoneName`                                   | `Oct 19 – 23, 2026`, `3 minutes ago`, `EEST`.                               |
+| `parse(text, { locale, kind, zone })`                                           | ISO, `Date`, epoch, HTTP date, or text in the locale's order.               |
+| `add` / `subtract` / `startOf` / `endOf` / `difference`                         | Calendar units on the wall clock, clock units on the instant.               |
+| `compare` / `isBefore` / `isAfter` / `isEqual` / `isSame` / `clamp`             | Across kinds and zones.                                                     |
+| `details(v, { zone })`                                                          | Every reading at once: `utc`, `zoned`, `local`, `offset`, `date`, `epoch`.  |
+| `weekInfo` / `hourCycleOf` / `monthNames` / `weekdayNames`                      | The locale, from `Intl`.                                                    |
+| `timeZones` / `offsetOf` / `isValidZone` / `normalizeZone`                      | The runtime's zones.                                                        |
+| `configureDates` / `localZone` / `systemZone` / `zoneCookie` / `readZoneCookie` | Who the reader is.                                                          |
+
+**DST** follows Temporal: a wall-clock time a zone skips or repeats takes `disambiguation` —
+`'compatible'` (default: the later reading of a skipped time, the earlier of a repeated one), `'earlier'`,
+`'later'` or `'reject'` (`null`).
+
+**The controls take and give the same string, and `onValueChange(value, details)` hands over the readings:**
+`details` is `{ reason, event, utc, local, zoned, date, epoch, zone, offset }`, all `null` while the value
+is. `reason` is `'keyboard'`, `'paste'`, `'select'`, `'preset'`, `'clear'` or `'reset'`.
+
+| Component (`components/…`)       | What it is                                                                                                                                                            |
+| -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `DateField` (`dateField`)        | Segments (`role="spinbutton"`) in the locale's order. `type`, `zone`, `granularity`, `hourCycle`, `min`/`max`, `isDateUnavailable`, `name`, `required`, `label`.      |
+| `Calendar` (`calendar`)          | APG's grid keys. `mode="range"` → `{ start, end }`, `months`, `weekNumbers`, `min`/`max`, `isDateUnavailable`, `firstDayOfWeek`.                                      |
+| `DatePicker` (`datePicker`)      | A `DateField` with a calendar (`date`), a list of times every `step` minutes (`time`) or both (`datetime`) in the top layer; `presets`, `clearable`, `closeOnSelect`. |
+| `DateRangePicker` (`datePicker`) | Two fields over a range calendar; `startName`/`endName`, `months` (2), `presets` of `{ start, end }`.                                                                 |
+| `TimeZoneSelect`                 | A `Combobox` over every zone, searchable by place, region or offset; the value is the IANA name.                                                                      |
+| `DateTime` (`dateTime`)          | `<time datetime>` in the reader's zone and language; `format`, `relative`, `zone`, `locale`. Also exports `DateProvider`.                                             |
+
+**A date-time's `zone`** is whose wall clock it is typed on: `'local'` (default), `'utc'`, an IANA name, or
+`'none'` (a wall clock with no zone, value `2026-10-19T14:30:00`). The value is the instant on that clock
+(`…+03:00`, or `…Z` for UTC), and a zone that is not the reader's is named after the time.
+
+**Four things to know.** **Nothing typed is ever parsed**: `03/04/2026` is two days depending on who typed
+it, so each segment is a spin button and only a paste is read as text. **No hydration error, ever**: a
+server and a hydrating browser both render in the fallback (`UTC`/`en-US`, or a `DateProvider`'s), and the
+render after hydration switches to the reader — so pass the cookie's zone to a `DateProvider` for a first
+paint that is already right. **`name` posts the canonical string** (and `required` is a real input the
+browser validates), so a server reads `2026-10-19` whatever the reader's locale. And in a **DataGrid**, a
+column takes `editor: 'date' | 'time' | 'datetime'` (inferred from an ISO string or a `Date`),
+`dateFormat: 'date' | 'time' | 'datetime' | 'relative' | Intl options` and `filterable: { type: 'date' }`
+(`on`/`before`/`after`/`between`, each day a `DatePicker`); those parts are a chunk the grid fetches only when it shows a date.
+Styling: `dateField` (extends `textbox`; `segment`, `literal`, `zone`, `label`; `compact`, `invalid`,
+`disabled`), `calendar` (`nav`, `title`, `weekday`, `weekNumber`, `cell` with the range band, `day` with
+`today`/`selected`/`outside`/`blocked`/`unavailable`, `zoomItem`) and `datePicker` (`trigger`, `clear`,
+`presets`, `preset`, `times`, `time`, `part`); the panel is a `popover`.
+
 ## Toaster (`toast()` + `<Toaster>`)
 
 ```tsx
@@ -2476,7 +2614,7 @@ function TrendCell({ cell }: { cell: CellModel<Row> }) {
 4. **fontSize divider is 16** (not 4). `fontSize={14}` → 14px
 5. **Spacing divider is 4**. `p={4}` → 16px (1rem)
 6. **Border width and lineHeight are direct px**. `b={1}` → 1px. **borderRadius uses divider 4**: `borderRadius={2}` → 8px
-7. **Colors are Tailwind's OKLCH palette**: `'gray-500'`, `'blue-600'` — 26 families × 11 steps, and an opacity modifier on any of them: `bgColor="blue-500/40"` (a `color-mix`, not `opacity`)
+7. **Colors are Tailwind's OKLCH palette**: `'gray-500'`, `'blue-600'` — 26 families × 11 steps, and an opacity modifier on any of them: `bgColor="blue-500/40"` (a `color-mix`, not `opacity`). The built-in components are drawn in two more, `accent` and `base`, which `Box.palette()` repoints
 8. **Breakpoints are mobile-first**: base → sm → md → lg → xl → xxl
 9. **Theme styles nest**: `theme={{ dark: { hover: { ... } } }}`
 10. **HTML attributes go in `props` prop**: `<Link props={{ href: '/about' }}>` not `<Link href>`. `data-*` and `aria-*` go there too — a `data-state` written at the top level typechecks and is then dropped
@@ -2796,11 +2934,13 @@ the same function — and an answer to an edit the user has since abandoned is d
 ```
 
 - **Which editor a cell opens is read off the value in it** — a number gets `number`, a boolean
-  `checkbox`, everything else `text` — unless `column.editor` names one (`text`/`number`/`checkbox`/
-  `select`) or configures it (`{ type, options?, placeholder?, step?, min?, max? }`; `options` may be a
-  function of the row). `column.EditCell` is a control of your own, bound to `cell.draft` with
-  `cell.setDraft(v)`, `cell.commitEdit()` and `cell.cancelEdit()` — the same three calls the built-in four
-  make.
+  `checkbox` (drawn as a check or a cross, read out as `localeText.booleanTrue`/`booleanFalse`), an ISO
+  date, time or date-time a `DateField` (an edit keeps the shape the cell held: `…Z` stays UTC, a `Date`
+  a `Date`), everything else `text` — unless `column.editor` names one of the seven
+  (`text`/`number`/`checkbox`/`select`/`date`/`time`/`datetime`) or configures it
+  (`{ type, options?, placeholder?, step?, min?, max?, zone? }`; `options` may be a function of the row).
+  `column.EditCell` is a control of your own, bound to `cell.draft` with `cell.setDraft(v)`,
+  `cell.commitEdit()` and `cell.cancelEdit()` — the same three calls the built-in seven make.
 - **Pointer:** a press makes a cell the current one — it takes the ring, whether the pointer or the
   keyboard put it there — and a **double press opens the editor** on an editable cell. A cell that cannot
   be edited takes both as focus and nothing else, and a double press landing on a widget inside a cell (a

package/box.cjs

@@ -1 +1 @@
-Object.defineProperties(exports,{__esModule:{value:!0},[Symbol.toStringTag]:{value:`Module`}});const e=require("./rolldown-runtime.cjs"),t=require("./react-shared.cjs"),n=require("./client.cjs");let r=require("react");r=e.t(r,1);let i=require("@box-kite/core");function a({tag:e,tagProps:t,render:n}){let[i,a]=(0,r.useState)(!1);return r.default.createElement(e,{...t,onMouseEnter:()=>a(!0),onMouseLeave:()=>a(!1)},n({isHover:i}))}function o(e,i){let{tag:o=`div`,children:s}=e,{classNames:c,styleElements:l}=n.a(e,o===`svg`),u=t.d(e,c);i&&(u.ref=i);let d=typeof s==`function`?r.default.createElement(a,{tag:o,tagProps:u,render:s}):r.default.createElement(o,u,s);return l?r.default.createElement(r.default.Fragment,null,l,d):d}var s=t.f(o,`Box`);s.extend=i.BoxExtends.extend,s.components=i.BoxExtends.components,s.createComponents=i.BoxExtends.createComponents,s.Components=n.s,s.keyframes=i.BoxExtends.keyframes,s.spring=i.Springs.spring,s.Theme=n.r,s.useTheme=n.r.useTheme,s.getVariableValue=e=>(0,i.getDefaultEngine)().getVariableValue(e),s.configure=n.i.configure,s.viewTransition=i.startViewTransition;function c(e,r){return t.p(n.a(e,r?.svg===!0),e.className)}exports.default=s,exports.useBoxElement=o,exports.useClassNames=c,exports.useVisibility=n.o;
+Object.defineProperties(exports,{__esModule:{value:!0},[Symbol.toStringTag]:{value:`Module`}});const e=require("./rolldown-runtime.cjs"),t=require("./react-shared.cjs"),n=require("./client.cjs");let r=require("react");r=e.t(r,1);let i=require("@box-kite/core");function a({tag:e,tagProps:t,render:n}){let[i,a]=(0,r.useState)(!1);return r.default.createElement(e,{...t,onMouseEnter:()=>a(!0),onMouseLeave:()=>a(!1)},n({isHover:i}))}function o(e,i){let{tag:o=`div`,children:s}=e,{classNames:c,styleElements:l}=n.i(e,o===`svg`),u=t.d(e,c);i&&(u.ref=i);let d=typeof s==`function`?r.default.createElement(a,{tag:o,tagProps:u,render:s}):r.default.createElement(o,u,s);return l?r.default.createElement(r.default.Fragment,null,l,d):d}var s=t.f(o,`Box`);s.extend=i.BoxExtends.extend,s.components=i.BoxExtends.components,s.palette=i.BoxExtends.palette,s.createComponents=i.BoxExtends.createComponents,s.Components=n.o,s.keyframes=i.BoxExtends.keyframes,s.spring=i.Springs.spring,s.Theme=n.n,s.useTheme=n.n.useTheme,s.useDesign=n.n.useDesign,s.getVariableValue=e=>(0,i.getDefaultEngine)().getVariableValue(e),s.configure=n.r.configure,s.viewTransition=i.startViewTransition;function c(e,r){return t.p(n.i(e,r?.svg===!0),e.className)}exports.default=s,exports.useBoxElement=o,exports.useClassNames=c,exports.useVisibility=n.a;

package/box.d.ts

@@ -21,6 +21,8 @@ interface BoxType {
     <TTag extends keyof React.JSX.IntrinsicElements = 'div', TKey extends keyof ComponentsAndVariants = never>(props: BoxCoreProps<TTag, TKey> & RefAttributes<ExtractElementFromTag<TTag>>): React.ReactNode;
     extend: typeof BoxExtends.extend;
     components: typeof BoxExtends.components;
+    /** The `vars` record that points the components' `accent` and `base` families at others, for an element and its subtree. */
+    palette: typeof BoxExtends.palette;
     /** A design for one subtree, registered nowhere: hand it to `<Box.Components value>` or `<Box.Theme components>`. */
     createComponents: typeof BoxExtends.createComponents;
     /** Every Box below resolves its `component` against this registry instead of the app's `Box.components()`. */
@@ -30,6 +32,8 @@ interface BoxType {
     spring: typeof Springs.spring;
     Theme: typeof Theme;
     useTheme: typeof Theme.useTheme;
+    /** Read the design the nearest `<Box.Theme>` draws in, and set it — `data-design` on its root. */
+    useDesign: typeof Theme.useDesign;
     getVariableValue: (name: string) => string;
     /** Explicit engine configuration (class-name hashing, style sink). Call once, before the first render. */
     configure: typeof StylesContext.configure;
@@ -60,3 +64,4 @@ export declare function useClassNames<TKey extends keyof ComponentsAndVariants =
 }): BoxClassNames;
 export { useVisibility };
 export type { BoxClassNames, BoxClassNameProps };
+export type { BoxComponentStyles, BoxStyleProps } from '@box-kite/core/types';

package/box.mjs

@@ -1,5 +1,5 @@
 import { d as e, f as t, p as n } from "./react-shared.mjs";
-import { a as r, i, o as a, r as o, s } from "./client.mjs";
+import { a as r, i, n as a, o, r as s } from "./client.mjs";
 import c, { useState as l } from "react";
 import { BoxExtends as u, Springs as d, getDefaultEngine as f, startViewTransition as p } from "@box-kite/core";
 //#region src/box.ts
@@ -12,19 +12,19 @@ function m({ tag: e, tagProps: t, render: n }) {
 	}, n({ isHover: r }));
 }
 function h(t, n) {
-	let { tag: i = "div", children: a } = t, { classNames: o, styleElements: s } = r(t, i === "svg"), l = e(t, o);
+	let { tag: r = "div", children: a } = t, { classNames: o, styleElements: s } = i(t, r === "svg"), l = e(t, o);
 	n && (l.ref = n);
 	let u = typeof a == "function" ? c.createElement(m, {
-		tag: i,
+		tag: r,
 		tagProps: l,
 		render: a
-	}) : c.createElement(i, l, a);
+	}) : c.createElement(r, l, a);
 	return s ? c.createElement(c.Fragment, null, s, u) : u;
 }
 var g = t(h, "Box");
-g.extend = u.extend, g.components = u.components, g.createComponents = u.createComponents, g.Components = s, g.keyframes = u.keyframes, g.spring = d.spring, g.Theme = o, g.useTheme = o.useTheme, g.getVariableValue = (e) => f().getVariableValue(e), g.configure = i.configure, g.viewTransition = p;
+g.extend = u.extend, g.components = u.components, g.palette = u.palette, g.createComponents = u.createComponents, g.Components = o, g.keyframes = u.keyframes, g.spring = d.spring, g.Theme = a, g.useTheme = a.useTheme, g.useDesign = a.useDesign, g.getVariableValue = (e) => f().getVariableValue(e), g.configure = s.configure, g.viewTransition = p;
 function _(e, t) {
-	return n(r(e, t?.svg === !0), e.className);
+	return n(i(e, t?.svg === !0), e.className);
 }
 //#endregion
-export { g as default, h as useBoxElement, _ as useClassNames, a as useVisibility };
+export { g as default, h as useBoxElement, _ as useClassNames, r as useVisibility };