@reddb-io/ui-kit 0.3.4 → 0.3.6

package/vendor/ds/kits/base/src/field.variants.ts

@@ -0,0 +1,54 @@
+// Field's public association and appearance seams.
+//
+// The association object is deliberately control-agnostic: Field can own the
+// accessible contract for the canonical Input or for a consumer's explicitly
+// named local control without either implementation reaching into the other.
+
+import { tv, type VariantProps } from "tailwind-variants";
+import type { FieldLayout } from "./core/field";
+
+export { FIELD_LAYOUTS, type FieldLayout, type FieldControlProps } from "./core/field";
+
+// `layout` decides where the label sits relative to its control. A text-like
+// control reads label-first, stacked above it. A binary choice — a checkbox or
+// a switch — reads control-first: the box sits at the start of the row, its
+// label beside it (and clickable, through the same native `for`), and help and
+// error text wrap underneath, aligned with the label text rather than with the
+// box. The association contract is identical in both.
+const LAYOUT = {
+  stacked: { root: "", label: "", help: "", error: "" },
+  inline: {
+    root: "grid-cols-[auto_minmax(0,1fr)] items-center gap-x-[var(--reddb-spatial-gap-md)]",
+    label: "cursor-pointer",
+    help: "col-start-2",
+    error: "col-start-2",
+  },
+} as const satisfies Record<FieldLayout, Record<string, string>>;
+
+// A disabled control takes its label down with it: the label steps to
+// secondary ink (still AA, WCAG 1.4.3) so a dimmed control never sits beside a
+// full-strength name. It follows the control's own `:disabled` — a native
+// `disabled` or an enclosing disabled fieldset — and only a control's: a
+// disabled <option> inside an enabled Select leaves the label alone. The
+// required mark carries no colour of its own, so it steps down with the label.
+//
+// The error is set in the danger feedback foreground, which the contrast
+// contract holds at AA on every ground; the message text, not the colour,
+// carries the meaning (WCAG 1.4.1).
+export const field = tv({
+  slots: {
+    root: "group/field grid content-start gap-[var(--reddb-spatial-gap-sm)]",
+    label: [
+      "text-sm font-medium text-foreground",
+      "group-has-[:is(input,select,textarea,button):disabled]/field:cursor-not-allowed",
+      "group-has-[:is(input,select,textarea,button):disabled]/field:text-ink-muted",
+    ].join(" "),
+    required: "ms-[var(--reddb-spatial-gap-sm)]",
+    help: "text-sm text-ink-muted",
+    error: "text-sm font-medium text-feedback-danger-foreground",
+  },
+  variants: { layout: LAYOUT },
+  defaultVariants: { layout: "stacked" },
+});
+
+export type FieldVariants = VariantProps<typeof field>;

package/vendor/ds/kits/base/src/fieldset.variants.ts

@@ -0,0 +1,29 @@
+// Fieldset's association and appearance seams preserve the native group while
+// naming only DS roles.
+import { tv, type VariantProps } from "tailwind-variants";
+import { field } from "./field.variants";
+
+export type { FieldsetControlProps } from "./core/fieldset";
+
+// The group owns its rhythm from the Density layout tier (ADR 0024): the
+// legend sits `layout-gap-sm` above the first field, and fields sit
+// `layout-gap-sm` apart (8/12/16/24px) — tighter than a Form's rows, so a
+// group's fields read as one group inside a Form.
+//
+// The legend steps to secondary ink when the group is disabled, exactly as a
+// Field's label follows its control. A nested group inside a disabled one is
+// disabled too (HTML), so its legend steps down with it. Help and error text
+// are Field's own, so a group's error reads like every other control's.
+export const fieldset = tv({
+  slots: {
+    root: "group/fieldset grid min-w-0 gap-[var(--reddb-spatial-layout-gap-sm)] border-0 p-0",
+    legend: [
+      "mb-[var(--reddb-spatial-layout-gap-sm)] text-sm font-medium text-foreground",
+      "group-disabled/fieldset:text-ink-muted",
+    ].join(" "),
+    help: field().help(),
+    error: field().error(),
+  },
+});
+
+export type FieldsetVariants = VariantProps<typeof fieldset>;

package/vendor/ds/kits/base/src/file-input.variants.ts

@@ -0,0 +1,18 @@
+// FileInput's public appearance seam composes the canonical Field and Input
+// skins, adding only the visible filename feedback owned by this capability.
+
+import { tv, type VariantProps } from "tailwind-variants";
+import { typeRoleMerge } from "./type-roles";
+import { field } from "./field.variants";
+import { input } from "./input.variants";
+
+export const fileInput = tv({
+  slots: {
+    root: "grid gap-[var(--reddb-spatial-gap-sm)]",
+    field: field().root(),
+    control: input(),
+    filename: "text-sm text-ink-muted",
+  },
+}, typeRoleMerge);
+
+export type FileInputVariants = VariantProps<typeof fileInput>;

package/vendor/ds/kits/base/src/form.variants.ts

@@ -0,0 +1,13 @@
+// Form's public scaffold seam. The Form owns the rhythm between its own rows —
+// fields, groups and the action row — and draws it from the Density layout
+// tier (ADR 0024): `layout-gap-md`, 16/20/24/40px from tiny to spacious. A
+// Field's label sits `gap-sm` from its control, never more than a quarter of
+// that, so each label reads with its own control. Local arrangement (columns,
+// an inline action row) stays extensible through `class`.
+import { tv, type VariantProps } from "tailwind-variants";
+
+export const form = tv({
+  base: "grid gap-[var(--reddb-spatial-layout-gap-md)]",
+});
+
+export type FormVariants = VariantProps<typeof form>;

package/vendor/ds/kits/base/src/grid-list.variants.ts

@@ -0,0 +1,38 @@
+// GridList's columns answer to the width of the list itself, never the window
+// (ADR 0021). The list stays the component's root (`<ul>`, which its child
+// Kits and their callers address directly), and an element cannot query its
+// own size, so the steps are written intrinsically instead: each track's
+// minimum is a step function of the list's inline size (`100%` in a grid
+// track is the grid's own width) that `auto-fill` turns into a column count.
+//
+// For `columns={4}` the track minimum is the largest of
+//   - a quarter of the row                      (always: 4 columns fit),
+//   - half the row,  while narrower than `5xl`  (2 columns),
+//   - the whole row, while narrower than `lg`   (1 column),
+// where a term `min(…, (step - 100%) * 9999)` is the row-relative size below
+// `step` and negative — so ignored by `max()` — from `step` up. The steps are
+// the DS's named container sizes: `lg` 32rem, `3xl` 48rem, `5xl` 64rem, so a
+// track never narrows below about 15rem. Four columns step 4 → 2 → 1, never
+// leaving a single orphan on a second row; three step 3 → 2 → 1; two 2 → 1.
+//
+// Each term subtracts the gutters at the largest component gap and a pixel of
+// slack, so the count is exact at every List gap and never rounds down.
+import { tv, type VariantProps } from "tailwind-variants";
+
+export const GRID_LIST_COLUMNS = [1, 2, 3, 4] as const;
+export type GridListColumn = (typeof GRID_LIST_COLUMNS)[number];
+
+export const gridList = tv({
+  base: "grid w-full",
+  variants: {
+    columns: {
+      1: "grid-cols-1",
+      2: "grid-cols-[repeat(auto-fill,minmax(max(calc((100%_-_var(--reddb-spatial-gap-lg))_/_2_-_1px),min(calc(100%_-_1px),calc((var(--reddb-container-lg)_-_100%)*9999))),1fr))]",
+      3: "grid-cols-[repeat(auto-fill,minmax(max(calc((100%_-_2*var(--reddb-spatial-gap-lg))_/_3_-_1px),min(calc((100%_-_var(--reddb-spatial-gap-lg))_/_2_-_1px),calc((var(--reddb-container-3xl)_-_100%)*9999)),min(calc(100%_-_1px),calc((var(--reddb-container-lg)_-_100%)*9999))),1fr))]",
+      4: "grid-cols-[repeat(auto-fill,minmax(max(calc((100%_-_3*var(--reddb-spatial-gap-lg))_/_4_-_1px),min(calc((100%_-_var(--reddb-spatial-gap-lg))_/_2_-_1px),calc((var(--reddb-container-5xl)_-_100%)*9999)),min(calc(100%_-_1px),calc((var(--reddb-container-lg)_-_100%)*9999))),1fr))]",
+    },
+  },
+  defaultVariants: { columns: 1 },
+});
+
+export type GridListVariants = VariantProps<typeof gridList>;

package/vendor/ds/kits/base/src/heading.variants.ts

@@ -0,0 +1,35 @@
+// Heading: a document level and a type role, decided separately (ADR 0025).
+//
+// The level is the outline (`h1`…`h6`); the role is the look, and it is one of
+// the Theme's heading roles. Every size, line height, tracking and weight
+// comes from the role's own text utility, so a Marketing island renders
+// larger type than the Application page around it without the Heading
+// knowing either direction exists.
+import { tv, type VariantProps } from "tailwind-variants";
+import { typeRoleMerge } from "./type-roles";
+
+const ROLE = {
+  display: "text-display",
+  title: "text-title",
+  heading: "text-heading",
+} as const;
+
+export const heading = tv(
+  {
+    base: "text-foreground text-balance",
+    variants: { role: ROLE },
+    defaultVariants: { role: "heading" },
+  },
+  typeRoleMerge,
+);
+
+export type HeadingVariants = VariantProps<typeof heading>;
+export type HeadingRole = NonNullable<HeadingVariants["role"]>;
+export const HEADING_ROLES = Object.keys(ROLE) as readonly HeadingRole[];
+export const HEADING_LEVELS = [1, 2, 3, 4, 5, 6] as const;
+export type HeadingLevel = (typeof HEADING_LEVELS)[number];
+
+/** The role a level reads as when none is chosen: a page title, then section headings. */
+export function defaultHeadingRole(level: HeadingLevel): HeadingRole {
+  return level === 1 ? "title" : "heading";
+}

package/vendor/ds/kits/base/src/image.variants.ts

@@ -0,0 +1,121 @@
+import { tv, type VariantProps } from "tailwind-variants";
+
+/**
+ * The Image's appearance: a block that never overflows its container, whose
+ * box is reserved before the bytes arrive (the intrinsic `width`/`height` or
+ * the caller's `ratio` set it), and whose fit and focal position are named
+ * values rather than raw `object-*` declarations.
+ */
+export const image = tv({
+  base: "block h-auto max-w-full",
+  variants: {
+    /** How the picture fills the box its dimensions or ratio reserve. */
+    fit: {
+      cover: "object-cover",
+      contain: "object-contain",
+    },
+    /** The focal point kept in frame when `cover` crops. */
+    position: {
+      center: "object-center",
+      top: "object-top",
+      bottom: "object-bottom",
+      start: "object-left",
+      end: "object-right",
+    },
+  },
+  defaultVariants: { fit: "cover", position: "center" },
+});
+
+export type ImageVariants = VariantProps<typeof image>;
+export type ImageFit = NonNullable<ImageVariants["fit"]>;
+export type ImagePosition = NonNullable<ImageVariants["position"]>;
+
+export const IMAGE_FITS = ["cover", "contain"] as const satisfies readonly ImageFit[];
+export const IMAGE_POSITIONS = [
+  "center",
+  "top",
+  "bottom",
+  "start",
+  "end",
+] as const satisfies readonly ImagePosition[];
+
+/** One `<source>` of a `<picture>`: a modern format or an art-directed crop the app produced. */
+export interface ImageSource {
+  /** Candidate URLs with `w` or `x` descriptors, as the app's asset pipeline wrote them. */
+  srcset: string;
+  /** MIME type the browser checks before choosing this source, such as `image/avif`. */
+  type?: string;
+  /** Media condition for an art-directed crop, such as `(min-width: 48rem)`. */
+  media?: string;
+  /** Slot widths for this source's `w` descriptors; the Image's `sizes` when omitted. */
+  sizes?: string;
+}
+
+/**
+ * The image an application's asset pipeline produced, as a composite accepts it.
+ *
+ * The DS never resizes or re-encodes anything: the application owns its
+ * pipeline and passes the URLs (and the intrinsic size) that pipeline wrote.
+ */
+export interface ImageAsset {
+  /** Fallback URL, used when no `srcset` candidate or `source` applies. */
+  src: string;
+  /** Text alternative. Empty only together with `decorative`. */
+  alt: string;
+  /** The image carries no information; renders `alt=""`. */
+  decorative?: boolean;
+  /** Intrinsic width in px of `src`. */
+  width?: number;
+  /** Intrinsic height in px of `src`. */
+  height?: number;
+  /** Width divided by height, when the intrinsic size is unknown. */
+  ratio?: number;
+  /** Width- or density-described candidates of the same picture. */
+  srcset?: string;
+  /** Slot widths for the `srcset` candidates. */
+  sizes?: string;
+  /** `<picture>` sources tried before the `img`, in order (AVIF, then WebP, …). */
+  sources?: readonly ImageSource[];
+}
+
+/**
+ * Refuse an image that would hide from assistive technology or shift the
+ * layout: `alt=""` only with `decorative`, and a box from `width` and
+ * `height` or from `ratio`. Thrown rather than warned — an unsized or
+ * unlabelled image is a defect in every Theme × Color Scheme × Density.
+ */
+export function assertImageContract(asset: {
+  alt?: string;
+  decorative?: boolean;
+  width?: number;
+  height?: number;
+  ratio?: number;
+}): void {
+  if (asset.decorative) {
+    if (asset.alt) {
+      throw new Error(
+        `Image: a decorative image renders alt="", so its alt ${JSON.stringify(asset.alt)} would be dropped; drop decorative or the alt.`,
+      );
+    }
+  } else if (typeof asset.alt !== "string" || asset.alt.trim() === "") {
+    throw new Error(
+      'Image: alt is required; pass decorative to mean the image carries no information (alt="").',
+    );
+  }
+  const sized = isPositive(asset.width) && isPositive(asset.height);
+  if (!sized && !isPositive(asset.ratio)) {
+    throw new Error(
+      "Image: pass width and height (the intrinsic size) or ratio, so the image reserves its box before it loads.",
+    );
+  }
+}
+
+function isPositive(value: number | undefined): value is number {
+  return typeof value === "number" && Number.isFinite(value) && value > 0;
+}
+
+/** The aspect ratio an Image reserves: the caller's `ratio`, else its intrinsic size. */
+export function imageRatio(asset: { width?: number; height?: number; ratio?: number }): number {
+  if (isPositive(asset.ratio)) return asset.ratio;
+  return (asset.width as number) / (asset.height as number);
+}