@ultimat3/ui 24.0.0 → 25.0.0

package/src/form/form-binding.ts

@@ -99,13 +99,19 @@ function declaredFields(fields: readonly string[]): ReadonlySet<string> {
   return declared;
 }
 
-export function createFormBinding<TValues, TResult>(
+export function formBinding<TValues, TResult>(
   options: FormBindingOptions<TValues, TResult>,
 ): FormBinding<TValues, TResult> {
   const fields = declaredFields(options.fields);
   let state: FormState<TResult> = IDLE_FORM_STATE;
   let touch: FormTouch = NO_FORM_TOUCH;
   let inFlight: Promise<FormState<TResult>> | null = null;
+  /**
+   * The paths changed since the in-flight submit read the form, or `null` with none in flight.
+   * Every edit counts, a revert to `initial` included: the server now holds what was submitted,
+   * not the opening value, so the baseline cannot say whether an edit made after the read is lost.
+   */
+  let editedInFlight: Set<string> | null = null;
 
   /**
    * A transition names the submit's own members; `touched`/`dirty` are added here, from the one
@@ -146,6 +152,9 @@ export function createFormBinding<TValues, TResult>(
   const run = async (values: TValues): Promise<FormState<TResult>> => {
     // Cleared, never carried: a stale message would mark a control invalid for a value the user
     // has already changed, on the one screen where the user is watching for exactly that.
+    // Opened BEFORE the publish: `onState` is synchronous, so a subscriber can edit in reaction
+    // to `submitting` itself, and that edit already postdates what this submit read.
+    editedInFlight = new Set();
     publish({ status: 'submitting', ...NO_FORM_ERRORS, result: undefined, issues: [] });
 
     try {
@@ -159,12 +168,16 @@ export function createFormBinding<TValues, TResult>(
         if (local.length > 0) return failed(local);
       }
       const result = await options.submit(values);
-      // The server accepted what the form held, so there is nothing left to lose. `touched` stays:
-      // the user has still visited those fields, and a hint that vanishes on save is a flicker.
-      touch = { touched: touch.touched, dirty: NO_FORM_TOUCH.dirty };
+      // The server accepted what the form held WHEN IT SUBMITTED, so only what changed since is
+      // left to lose — clearing that too let a navigation guard drop an edit typed during the save.
+      // `touched` stays: the user has still visited those fields, and a hint that vanishes on save
+      // is a flicker.
+      touch = { touched: touch.touched, dirty: editedInFlight ?? NO_FORM_TOUCH.dirty };
       return publish({ status: 'succeeded', ...NO_FORM_ERRORS, result, issues: [] });
     } catch (rejection) {
       return failed(issuesFromRejection(rejection));
+    } finally {
+      editedInFlight = null;
     }
   };
 
@@ -184,10 +197,14 @@ export function createFormBinding<TValues, TResult>(
     pending: () => state.status === 'submitting',
     firstInvalidField: () => firstInvalidField(state, fields),
     touch: (path) => publishTouch(markTouched(touch, path)),
-    edit: (path, value) =>
-      publishTouch(markDirty(touch, path, !sameFieldValue(value, baseline(path)))),
+    edit: (path, value) => {
+      editedInFlight?.add(path);
+      publishTouch(markDirty(touch, path, !sameFieldValue(value, baseline(path))));
+    },
     reset: () => {
       touch = NO_FORM_TOUCH;
+      // A reset mid-flight discards what was typed before it, the in-flight window's share too.
+      if (editedInFlight !== null) editedInFlight = new Set();
       publish(IDLE_FORM_STATE);
     },
   };

package/src/form/use-form.ts

@@ -1,11 +1,11 @@
-// The reactive shell over `createFormBinding`, and the whole of what it adds: the state lands in a
+// The reactive shell over `formBinding`, and the whole of what it adds: the state lands in a
 // signal, so a `<Field error={form.errorFor('title')}>` re-renders when a submit answers.
 //
 // Reactivity goes through `solid()` like every other read in this package — a component that
 // imported solid-js directly would make @ultimat3/ui depend on a runtime it deliberately does not.
 
 import { solid } from '../theme/solid-adapter';
-import { createFormBinding, type FormBinding, type FormBindingOptions } from './form-binding';
+import { type FormBinding, type FormBindingOptions, formBinding } from './form-binding';
 import {
   errorOf,
   type FormState,
@@ -24,7 +24,7 @@ export function useForm<TValues, TResult>(
 ): FormBinding<TValues, TResult> {
   const runtime = solid();
   const [state, setState] = runtime.createSignal<FormState<TResult>>(IDLE_FORM_STATE);
-  const binding = createFormBinding<TValues, TResult>({
+  const binding = formBinding<TValues, TResult>({
     ...options,
     onState: (next) => {
       options.onState?.(next);

package/src/global.scss

@@ -5,3 +5,12 @@
 
 @use 'tokens/theme';
 @use 'tokens/reset';
+
+// A held island's reveal that needs no script (`@ultimat3/render`'s `ISLAND_HOLD_REVEAL`, issue 506):
+// its wrapper animates to this after the hold's cap, so JS off or a blocked runtime still shows
+// the server's markup. The name is held equal to render's by `island-hold-replay.test.ts`.
+@keyframes ultimate-hold-reveal {
+  to {
+    visibility: visible;
+  }
+}

package/src/icons/build-icons.ts

@@ -23,7 +23,7 @@ export const LUCIDE_LATEST_URL = 'https://registry.npmjs.org/lucide-static/lates
 /** The tail of every cause about data the PIN published: why re-running alone cannot help. */
 const PIN_REPEATS = `lucide-static@${LUCIDE_VERSION} is the pin that published it, so a re-run against the same pin repeats this; \`--bump\` raises LUCIDE_VERSION in packages/ui/src/icons/build-icons.ts to the latest release and regenerates`;
 
-export const GLYPHS_DIR = new URL('./glyphs/', import.meta.url).pathname;
+export const GLYPHS_DIR = Bun.fileURLToPath(new URL('./glyphs/', import.meta.url));
 
 /** `circle-alert` → `iconCircleAlert`. Prefixed because `delete`, `import` and `package` are icons
  * and reserved words — one uniform rule beats three exceptions an agent has to remember. */
@@ -167,13 +167,22 @@ export function moduleSource(name: string, glyph: IconGlyph): string {
   ].join('\n');
 }
 
+/** The repo's own `node_modules/.bin`, where `bun install` links every tool binary. */
+const REPO_BIN = Bun.fileURLToPath(new URL('../../../../node_modules/.bin', import.meta.url));
+
+/**
+ * The biome executable in `binDir`, or `undefined`. Asked of `Bun.which` rather than spelled as
+ * `<bin>/biome`: on Windows the link is `biome.exe`, and a path with no extension is ENOENT there.
+ */
+export function biomeBinary(binDir: string = REPO_BIN): string | undefined {
+  return Bun.which('biome', { PATH: binDir }) ?? undefined;
+}
+
 /** Biome owns formatting in this repo, generated files included — so the generator asks it rather
  * than imitating it, and a regenerated set never shows up as a lint diff. */
 async function format(): Promise<void> {
-  const biome = new URL('../../../../node_modules/.bin/biome', import.meta.url).pathname;
-  if (!(await Bun.file(biome).exists())) {
-    throw runtimeMissingError('the biome binary', 'bun install');
-  }
+  const biome = biomeBinary();
+  if (biome === undefined) throw runtimeMissingError('the biome binary', 'bun install');
   // A formatter over one directory of generated files; a wedged one is the refusal below.
   const result = Bun.spawnSync([biome, 'format', '--write', GLYPHS_DIR], { timeout: 60_000 });
   if (result.exitCode !== 0) {
@@ -235,7 +244,7 @@ async function bumpPin(): Promise<string> {
   const body: unknown = await response.json();
   const version =
     typeof body === 'object' && body !== null && 'version' in body ? String(body.version) : '';
-  const file = new URL(import.meta.url).pathname;
+  const file = import.meta.path;
   await Bun.write(file, withPin(await Bun.file(file).text(), version));
   return version;
 }

package/src/index.ts

@@ -22,13 +22,13 @@ export type {
 export {
   announce,
   ariaBool,
-  createFocusTrap,
-  createRovingTabindex,
   FOCUSABLE_SELECTOR,
   focusableWithin,
+  focusTrap,
   LIVE_REGION_LEVELS,
   liveRegionAttrs,
-  resetIdCounter,
+  resetUseIdCounter,
+  rovingTabindex,
   useId,
 } from './a11y';
 export type { AccordionItem, AccordionProps } from './components/Accordion';
@@ -70,6 +70,8 @@ export type { BarRect, ChartPoint } from './components/bar-chart-view';
 export { barRects } from './components/bar-chart-view';
 export type { CardProps, Elevation } from './components/Card';
 export { Card } from './components/Card';
+export type { ChartFrameProps, ChartLegendItem } from './components/ChartFrame';
+export { ChartFrame } from './components/ChartFrame';
 export type { CheckboxProps } from './components/Checkbox';
 export { Checkbox } from './components/Checkbox';
 export type { ComboboxProps } from './components/Combobox';
@@ -80,6 +82,17 @@ export type { ContainerProps, ContainerSize } from './components/Container';
 export { Container } from './components/Container';
 export type { CopyButtonProps } from './components/CopyButton';
 export { COPIED_MS, CopyButton } from './components/CopyButton';
+export type {
+  ChartSeries,
+  ChartTable,
+  ChartTableInput,
+  ChartTableRow,
+  MarkerShape,
+  SeriesStyle,
+} from './components/chart-frame-view';
+export { CHART_SERIES_SLOTS, chartTable, seriesStyle } from './components/chart-frame-view';
+export type { NiceScale, NiceTicksOptions } from './components/chart-ticks-view';
+export { niceTicks } from './components/chart-ticks-view';
 export type { ComboboxOption } from './components/combobox-filter';
 export { filterOptions, normalizeQuery } from './components/combobox-filter';
 export type { CommandPaletteItem, PaletteKeyAction } from './components/command-palette-view';
@@ -93,6 +106,7 @@ export type {
   Column,
   DataTableCallbackProps,
   DataTableLinkProps,
+  DataTableNarrow,
   DataTableProps,
 } from './components/DataTable';
 export { DataTable } from './components/DataTable';
@@ -102,10 +116,13 @@ export type { DialogProps } from './components/Dialog';
 export { Dialog } from './components/Dialog';
 export type { DividerProps } from './components/Divider';
 export { Divider } from './components/Divider';
+export type { DonutChartProps, DonutSegment } from './components/DonutChart';
+export { DonutChart } from './components/DonutChart';
 export type { DrawerProps, DrawerSide } from './components/Drawer';
 export { Drawer } from './components/Drawer';
 export type { DropzoneProps } from './components/Dropzone';
 export { Dropzone } from './components/Dropzone';
+export type { ColumnPriority } from './components/data-table-view';
 export type {
   DateStyle,
   DateTimeFormatter,
@@ -133,9 +150,11 @@ export type {
   FileTarget,
 } from './components/file-input-view';
 export {
-  formatBytes,
+  formatFileSize,
   selectFiles,
 } from './components/file-input-view';
+export type { GaugeProps } from './components/Gauge';
+export { Gauge } from './components/Gauge';
 export type { GridProps } from './components/Grid';
 export { Grid } from './components/Grid';
 export type { HeadingLevel, HeadingTag } from './components/heading-level';
@@ -149,6 +168,8 @@ export type { ImageBaseProps, ImageDimensions, ImageProps } from './components/I
 export { Image } from './components/Image';
 export type { InfiniteScrollProps } from './components/InfiniteScroll';
 export { InfiniteScroll } from './components/InfiniteScroll';
+export type { InlineBarProps } from './components/InlineBar';
+export { InlineBar } from './components/InlineBar';
 export type { InputProps, InputType } from './components/Input';
 export { Input } from './components/Input';
 export type { IconElement, IconGlyph, IconTag } from './components/icon-glyph';
@@ -161,10 +182,12 @@ export type {
   ImageSources,
   ImageVariant,
 } from './components/image-source';
-export { boxFor, reservedRatio, sourceSetsFor, srcsetFor } from './components/image-source';
+export { boxFor, reservedRatio, sourceSetsFor, variantSrcset } from './components/image-source';
 export type { LoadMoreInput, LoadMoreState } from './components/infinite-scroll-view';
 export type { KbdProps } from './components/Kbd';
 export { Kbd } from './components/Kbd';
+export type { AreaChartProps, LineChartProps } from './components/LineChart';
+export { AreaChart, LineChart } from './components/LineChart';
 export type { ButtonLinkProps, LinkProps, TextLinkProps } from './components/Link';
 export { Link } from './components/Link';
 export type { LocaleSwitcherProps } from './components/LocaleSwitcher';
@@ -265,7 +288,7 @@ export {
 export type { FieldPathSegment, IssuePathSegment } from './form/field-path';
 export { fieldSelector, formatFieldPath, MAX_FIELD_INDEX, parseFieldPath } from './form/field-path';
 export type { FormBinding, FormBindingOptions } from './form/form-binding';
-export { createFormBinding } from './form/form-binding';
+export { formBinding } from './form/form-binding';
 export type {
   FormIssue,
   FormSchema,
@@ -312,6 +335,9 @@ export {
   useUi,
 } from './theme/context';
 export { INERT_SOLID_RUNTIME } from './theme/inert-runtime';
+export type { ThemePreset } from './theme/preset-shape';
+export type { ThemePresetName } from './theme/presets';
+export { THEME_PRESET_NAMES, THEME_PRESETS } from './theme/presets';
 export type { UiProviderProps } from './theme/provider';
 export { UiProvider } from './theme/provider';
 // The slot is its own module so that registering a runtime does not drag `errors.ts` — and with it
@@ -334,7 +360,6 @@ export {
   THEME_ATTRIBUTE,
   THEME_DEFAULT_ATTRIBUTE,
   THEME_MEDIA_QUERY,
-  THEME_STORAGE_KEY,
   toggleTheme,
   watchOsTheme,
 } from './theme/theme';
@@ -352,8 +377,16 @@ export {
   TOAST_MAX_VISIBLE,
 } from './toast/toast-state';
 export type { ToastEnv, ToastStore } from './toast/toast-store';
-export { browserToastEnv, createToastStore, INERT_TOAST_ENV } from './toast/toast-store';
+export { browserToastEnv, INERT_TOAST_ENV, toastStore } from './toast/toast-store';
 export { useToasts } from './toast/use-toasts';
+export type { ColourVision } from './tokens/colour-vision';
+export {
+  CHART_DISTINCT_MIN,
+  COLOUR_VISIONS,
+  closestChartPair,
+  colourDistance,
+  simulateColourVision,
+} from './tokens/colour-vision';
 export type { Channels } from './tokens/contrast';
 export {
   AA_LARGE,
@@ -365,11 +398,12 @@ export {
 } from './tokens/contrast';
 export type { ContrastPair } from './tokens/contrast-pairs';
 export { CONTRAST_PAIRS } from './tokens/contrast-pairs';
-export type { ColorRole, RadiusName, Theme } from './tokens/tokens';
+export type { ChartRole, ColorRole, RadiusName, ShadowName, Theme } from './tokens/tokens';
 // --- tokens ------------------------------------------------------------------
 export {
   assertColorRole,
   breakpointTokens,
+  CHART_ROLES,
   COLOR_ROLES,
   color,
   colorRgb,
@@ -381,8 +415,10 @@ export {
   fontWeightTokens,
   lineHeightTokens,
   radiusTokens,
+  SHADOW_NAMES,
   shadowTokens,
   spaceTokens,
   strokeTokens,
+  touchTokens,
   zTokens,
 } from './tokens/tokens';

package/src/jsx-probe.ts

@@ -38,10 +38,11 @@ function h(
  *
  * There may be exactly ONE such counter in the framework, and it is this one — `globalThis.React`
  * is a single property, so a second module counting its own depth over it restores in the wrong
- * order. `@ultimat3/admin`'s `inert-jsx.ts` kept a second pair and the two interleaved: admin
- * installs (saving the real binding), ui installs (saving ADMIN's factory), admin restores (both
- * counters at 1 → the real binding is back), ui restores (its counter hits 0 → admin's factory is
- * reinstalled over it). The global ended up holding a harness the run had already torn down.
+ * order. `@ultimat3/admin`'s `inert-jsx-fixture.ts` kept a second pair and the two interleaved:
+ * admin installs (saving the real binding), ui installs (saving ADMIN's factory), admin restores
+ * (both counters at 1 → the real binding is back), ui restores (its counter hits 0 → admin's
+ * factory is reinstalled over it). The global ended up holding a harness the run had already torn
+ * down.
  * `admin` is tier 5 and `ui` is tier 4, so admin imports these rather than declaring them.
  */
 let depth = 0;

package/src/theme/brand-declarations.ts

@@ -0,0 +1,113 @@
+// The validators behind `defineTheme()`: each slot's override checked against its canonical list
+// and value grammar, then rendered as custom-property lines in that list's order — never the
+// caller's — so a brand rendered twice is byte-identical and its CSP hash does not churn.
+
+import { invalidBrandTokenError, unknownTokenError } from '../errors';
+import { parseChannels } from '../tokens/contrast';
+import {
+  COLOR_ROLES,
+  type ColorRole,
+  type RadiusName,
+  radiusTokens,
+  SHADOW_NAMES,
+  type ShadowName,
+} from '../tokens/tokens';
+import { FONT_SLOTS, type FontSlot } from './preset-shape';
+import { isShadowValue, SHADOW_EXPECTED } from './shadow-value';
+
+/** `0` or a number with a CSS length unit. No `calc()`, no `var()` — a scale rung is a value. */
+const LENGTH_PATTERN = /^(0|\d+(\.\d+)?(px|rem|em|ch|%))$/;
+
+/**
+ * Family names, quotes and separators only: everything a `font-family` list legitimately needs.
+ * The separator is a literal SPACE, never `\s`: the HTML parser rewrites a CR or CRLF inside a
+ * `<style>` to LF before the browser hashes it, so a stack carrying one served bytes whose sha256
+ * no longer matched the CSP hash computed here, and the brand's whole stylesheet was blocked.
+ */
+const FONT_STACK_PATTERN = /^[\w ,'"-]{1,200}$/;
+
+const LENGTH_EXPECTED = 'a bare CSS length such as "0.5rem", "4px" or "0"';
+const STACK_EXPECTED = 'a font-family list such as "Inter, system-ui, sans-serif"';
+const CHANNELS_EXPECTED = 'space-separated RGB channels such as "31 110 178"';
+
+function assertKnown(
+  kind: string,
+  overrides: object,
+  known: readonly string[],
+  source?: string,
+): void {
+  for (const name of Object.keys(overrides)) {
+    if (!known.includes(name)) throw unknownTokenError(kind, name, known, source);
+  }
+}
+
+export function colorDeclarations(
+  overrides: Partial<Record<ColorRole, string>> | undefined,
+  scope: string,
+): string[] {
+  if (overrides === undefined) return [];
+  assertKnown('color', overrides, COLOR_ROLES);
+  const out: string[] = [];
+  for (const role of COLOR_ROLES) {
+    const value = overrides[role];
+    if (value === undefined) continue;
+    try {
+      parseChannels(value);
+    } catch {
+      throw invalidBrandTokenError(scope, role, value, CHANNELS_EXPECTED);
+    }
+    out.push(`--color-${role}: ${value};`);
+  }
+  return out;
+}
+
+export function shadowDeclarations(
+  overrides: Partial<Record<ShadowName, string>> | undefined,
+  scope: string,
+): string[] {
+  if (overrides === undefined) return [];
+  assertKnown('shadow', overrides, SHADOW_NAMES, '_shadow.scss');
+  const out: string[] = [];
+  for (const name of SHADOW_NAMES) {
+    const value = overrides[name];
+    if (value === undefined) continue;
+    if (!isShadowValue(value)) throw invalidBrandTokenError(scope, name, value, SHADOW_EXPECTED);
+    out.push(`--shadow-${name}: ${value};`);
+  }
+  return out;
+}
+
+export function radiusDeclarations(
+  overrides: Partial<Record<RadiusName, string>> | undefined,
+): string[] {
+  if (overrides === undefined) return [];
+  const known = Object.keys(radiusTokens) as RadiusName[];
+  assertKnown('radius', overrides, known, '_radius.scss');
+  const out: string[] = [];
+  for (const name of known) {
+    const value = overrides[name];
+    if (value === undefined) continue;
+    if (!LENGTH_PATTERN.test(value)) {
+      throw invalidBrandTokenError('radius', name, value, LENGTH_EXPECTED);
+    }
+    out.push(`--radius-${name}: ${value};`);
+  }
+  return out;
+}
+
+export function fontDeclarations(
+  overrides: Partial<Record<FontSlot, string>> | undefined,
+): string[] {
+  if (overrides === undefined) return [];
+  assertKnown('font', overrides, FONT_SLOTS, '_typography.scss');
+  const out: string[] = [];
+  for (const slot of FONT_SLOTS) {
+    const value = overrides[slot];
+    if (value === undefined) continue;
+    if (!FONT_STACK_PATTERN.test(value)) {
+      throw invalidBrandTokenError('font', slot, value, STACK_EXPECTED);
+    }
+    out.push(`--font-${slot}: ${value};`);
+  }
+  return out;
+}