@pinfold/core 0.0.0-stage → 0.2.0

package/README.md

@@ -1,3 +1,42 @@
-# Temporary Holding Version
+# @pinfold/core
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The framework-free layer of [Pinfold](../../README.md): each component's behaviour rules, the
+helpers, keyboard rules, component metadata and the OKLCH palette engine that every Pinfold
+adapter shares. No React,
+no dependencies. A test fails the build if a framework import ever appears here.
+
+Most apps never install this directly. `@pinfold/react` depends on it.
+
+## Exports
+
+| | |
+| --- | --- |
+| `cn`, `mergeProps`, `composeRefs` | class joining and prop merging (handlers chain, styles merge) |
+| `variants` | `cva`-style class resolution |
+| `nextIndexFromKey` | the WAI-ARIA roving-focus key map (orientation, RTL, loop) |
+| `dimensionVars` | `dimensions` config → `--pinfold-<component>-*` custom properties |
+| `resolveNode`, `dataAttr`, `ariaAttr` | slot value and attribute helpers |
+| `warnOnce`, `__DEV__` | dev-only diagnostics, stripped in production |
+| `setAccordionItem`, `openAllAccordion`, `accordionFocusTarget`, … | the accordion's rules as pure functions |
+
+## Metadata
+
+`@pinfold/core/meta`: `accordionMeta` (every option, default, slot, keyboard key and ARIA rule),
+`validateConfig`, `toJsonSchema` and `metaToMarkdown`. Docs, the playground, the CLI, the MCP
+server and dev validation are all generated from it. Apps never ship it.
+
+## Palette
+
+```js
+import { createTheme, contrastRatio, toDTCG } from '@pinfold/core/palette';
+
+const theme = createTheme({ primary: 'emerald', accent: 'amber', radius: 'lg' });
+theme.vars;      // { '--pinfold-primary-500': '#009b60', … }
+theme.css;       // the stylesheet `npx pinfold theme` writes
+theme.contrast;  // WCAG report per role and step
+toDTCG(theme);   // W3C design tokens
+```
+
+Seven roles × eleven OKLCH steps, gamut-mapped, with sRGB hex fallbacks.
+
+MIT © Indranil Bhattacharya

package/dist/index.cjs

@@ -0,0 +1,242 @@
+'use strict';
+
+// src/utils.ts
+function cn(...parts) {
+  let out = "";
+  for (let i = 0; i < parts.length; i++) {
+    const p = parts[i];
+    if (p) out = out ? out + " " + p : p;
+  }
+  return out;
+}
+function resolveNode(value, state) {
+  return typeof value === "function" ? value(state) : value;
+}
+function dataAttr(condition) {
+  return condition ? "" : void 0;
+}
+function ariaAttr(condition) {
+  return condition ? "true" : void 0;
+}
+function composeRefs(...refs) {
+  return (node) => {
+    for (let i = 0; i < refs.length; i++) {
+      const ref = refs[i];
+      if (typeof ref === "function") ref(node);
+      else if (ref) ref.current = node;
+    }
+  };
+}
+var isHandler = (key) => key.length > 2 && key.charCodeAt(0) === 111 && key.charCodeAt(1) === 110;
+function mergeProps(base, overrides) {
+  if (!overrides) return base;
+  const out = { ...base };
+  for (const key in overrides) {
+    const ours = base[key];
+    const theirs = overrides[key];
+    if (isHandler(key) && typeof ours === "function" && typeof theirs === "function") {
+      out[key] = (...args) => {
+        ours(...args);
+        const ev = args[0];
+        if (ev && ev.defaultPrevented) return;
+        theirs(...args);
+      };
+    } else if (key === "className") {
+      out[key] = cn(ours, theirs);
+    } else if (key === "style") {
+      out[key] = { ...ours, ...theirs };
+    } else if (key === "ref") {
+      out[key] = composeRefs(ours, theirs);
+    } else {
+      out[key] = theirs;
+    }
+  }
+  return out;
+}
+
+// src/variants.ts
+function variants(config) {
+  const { base = "", variants: map, defaultVariants = {} } = config;
+  return function resolve(props) {
+    var _a;
+    let out = base;
+    for (const key in map) {
+      const chosen = (_a = props == null ? void 0 : props[key]) != null ? _a : defaultVariants[key];
+      if (chosen == null) continue;
+      const cls = map[key][chosen];
+      if (cls) out = cn(out, cls);
+    }
+    return cn(out, props == null ? void 0 : props.className);
+  };
+}
+
+// src/navigation.ts
+function nextIndexFromKey(key, current, count, { orientation = "vertical", dir = "ltr", loop = true } = {}) {
+  if (count === 0) return null;
+  const forward = orientation === "vertical" ? "ArrowDown" : dir === "rtl" ? "ArrowLeft" : "ArrowRight";
+  const backward = orientation === "vertical" ? "ArrowUp" : dir === "rtl" ? "ArrowRight" : "ArrowLeft";
+  switch (key) {
+    case forward: {
+      const next = current + 1;
+      return next < count ? next : loop ? 0 : current;
+    }
+    case backward: {
+      const prev = current - 1;
+      return prev >= 0 ? prev : loop ? count - 1 : current;
+    }
+    case "Home":
+      return 0;
+    case "End":
+      return count - 1;
+    default:
+      return null;
+  }
+}
+
+// src/dimensions.ts
+function dimensionVars(component, dimensions) {
+  if (!dimensions) return void 0;
+  const out = {};
+  for (const [key, raw] of Object.entries(dimensions)) {
+    const value = raw;
+    if (value === void 0 || value === null || value === "") continue;
+    out[`--pinfold-${component}-${kebab(key)}`] = typeof value === "number" ? `${value}px` : value;
+  }
+  return out;
+}
+var kebab = (s) => s.replace(/[A-Z]/g, (m) => "-" + m.toLowerCase());
+
+// src/accordion.logic.ts
+function accordionRowId(item, index) {
+  var _a;
+  return (_a = item.id) != null ? _a : String(index);
+}
+function accordionPartIds(baseId, rowId) {
+  return { triggerId: `${baseId}-trigger-${rowId}`, panelId: `${baseId}-panel-${rowId}` };
+}
+function normalizeAccordionValue(value, mode) {
+  return mode === "single" ? value.slice(0, 1) : value.slice();
+}
+function initialAccordionValue(items, defaultValue, mode) {
+  if (defaultValue) return normalizeAccordionValue(defaultValue, mode);
+  const open = [];
+  items.forEach((item, i) => {
+    if (item.defaultOpen) open.push(accordionRowId(item, i));
+  });
+  return normalizeAccordionValue(open, mode);
+}
+function setAccordionItem(value, rows, id, open, rules) {
+  const row = rows.find((r) => r.id === id);
+  if (!row || row.disabled || rules.disabled) return null;
+  const isOpen = value.indexOf(id) !== -1;
+  if (isOpen === open) return null;
+  if (!open && !rules.collapsible && value.length === 1) return null;
+  if (open) return rules.mode === "single" ? [id] : value.concat(id);
+  return value.filter((v) => v !== id);
+}
+function openAllAccordion(value, rows, rules) {
+  if (rules.mode === "single" || rules.disabled) return null;
+  const next = rows.filter((r) => !r.disabled || value.indexOf(r.id) !== -1).map((r) => r.id);
+  return sameSet(value, next) ? null : next;
+}
+function closeAllAccordion(value, rows, rules) {
+  if (rules.disabled || !rules.collapsible) return null;
+  const locked = new Set(rows.filter((r) => r.disabled).map((r) => r.id));
+  const next = value.filter((id) => locked.has(id));
+  return sameSet(value, next) ? null : next;
+}
+function accordionFocusTarget(key, index, count, options = {}) {
+  return nextIndexFromKey(key, index, count, options);
+}
+function mapAccordionFields(records, fields) {
+  if (!fields) return records;
+  return records.map((record) => {
+    const out = { ...record };
+    for (const key in fields) {
+      const source = fields[key];
+      if (source && record != null && source in record) {
+        const v = record[source];
+        out[key] = key === "id" && v != null ? String(v) : v;
+      }
+    }
+    return out;
+  });
+}
+var ZERO = /^0*\.?0*(px|rem|em|%|vh|vw)?$/;
+function accordionRowsJoined(variant = "solid", gap) {
+  if (gap === void 0 || gap === null || gap === "") return variant !== "separated" && variant !== "filled";
+  if (gap === "none" || gap === 0) return true;
+  return typeof gap === "string" && ZERO.test(gap.trim());
+}
+function inactiveAccordionOptions(input) {
+  var _a;
+  const variant = (_a = input.variant) != null ? _a : "solid";
+  const joined = accordionRowsJoined(variant, input.gap);
+  const card = variant === "solid" || variant === "outline";
+  const rows = variant === "separated" || variant === "filled";
+  const out = {};
+  if (variant === "ghost") {
+    out.radius = "Ghost has no surface to round. Pick solid or outline for a rounded container.";
+    out.itemRadius = "Ghost rows have no surface to round. Pick separated or filled for rounded rows.";
+  }
+  if (card) out.itemRadius = "In a solid or outline card the rows are not surfaces; the card takes `radius`.";
+  if (rows && joined) out.itemRadius = "With no gap the rows join into one group, rounded by `radius`.";
+  if (rows && !joined && input.itemRadius !== void 0) {
+    out.radius = 'Separated and filled rows are the surfaces and `itemRadius` already rounds them. Unset `itemRadius` so `radius` reaches the rows, or set `gap: "none"` to join them.';
+  }
+  if (rows && !joined) out.dividers = 'The rows are already apart. Dividers appear when `gap` is "none".';
+  if (input.indicator === "none") {
+    out.indicatorPosition = 'There is no indicator (`indicator: "none"`).';
+    out.animateIndicator = 'There is no indicator (`indicator: "none"`).';
+  }
+  if (input.disabled) out.disabledIds = "Every row is already disabled (`disabled: true`).";
+  return out;
+}
+function shouldMountPanel(policy, open, everOpened) {
+  if (policy === "always" || open) return true;
+  return policy === "first-open" && everOpened;
+}
+function sameSet(a, b) {
+  return a.length === b.length && a.every((v) => b.indexOf(v) !== -1);
+}
+
+// src/dev.ts
+var __DEV__ = typeof process !== "undefined" && !!process.env && process.env.NODE_ENV !== "production";
+var seen = /* @__PURE__ */ new Set();
+function warnOnce(condition, message) {
+  if (!__DEV__ || !condition || seen.has(message)) return;
+  seen.add(message);
+  console.warn(`[pinfold] ${message}`);
+}
+function resetWarnings() {
+  seen.clear();
+}
+
+// src/index.ts
+var version = "0.2.0";
+
+exports.__DEV__ = __DEV__;
+exports.accordionFocusTarget = accordionFocusTarget;
+exports.accordionPartIds = accordionPartIds;
+exports.accordionRowId = accordionRowId;
+exports.accordionRowsJoined = accordionRowsJoined;
+exports.ariaAttr = ariaAttr;
+exports.closeAllAccordion = closeAllAccordion;
+exports.cn = cn;
+exports.composeRefs = composeRefs;
+exports.dataAttr = dataAttr;
+exports.dimensionVars = dimensionVars;
+exports.inactiveAccordionOptions = inactiveAccordionOptions;
+exports.initialAccordionValue = initialAccordionValue;
+exports.mapAccordionFields = mapAccordionFields;
+exports.mergeProps = mergeProps;
+exports.nextIndexFromKey = nextIndexFromKey;
+exports.normalizeAccordionValue = normalizeAccordionValue;
+exports.openAllAccordion = openAllAccordion;
+exports.resetWarnings = resetWarnings;
+exports.resolveNode = resolveNode;
+exports.setAccordionItem = setAccordionItem;
+exports.shouldMountPanel = shouldMountPanel;
+exports.variants = variants;
+exports.version = version;
+exports.warnOnce = warnOnce;

package/dist/index.d.cts

@@ -0,0 +1,211 @@
+/** Shared scale used by every Pinfold component. */
+type PinfoldSize = 'sm' | 'md' | 'lg';
+type PinfoldRadius = 'none' | 'sm' | 'md' | 'lg' | 'full';
+type PinfoldTone = 'neutral' | 'primary' | 'success' | 'warning' | 'danger' | 'info';
+type PinfoldOrientation = 'horizontal' | 'vertical';
+type PinfoldDir = 'ltr' | 'rtl';
+type PinfoldTheme = 'light' | 'dark' | 'system';
+/** When a component's code loads. `auto`: light components eagerly, heavy ones when visible. */
+type PinfoldLazy = 'auto' | 'eager' | 'visible' | 'idle';
+/** Visual style pack, applied through `data-pinfold-style`. */
+type PinfoldStylePack = 'default' | 'glass' | 'material' | 'noise' | 'brutalist';
+/** Any DOM props bag a component hands back from a `getXProps()` call. */
+type PropsBag = Record<string, any>;
+/** A CSS length. Numbers are px, strings pass through (`'50%'`, `'12rem'`, `calc()`). */
+type Length = number | string;
+/** A callback ref or a `{ current }` object, the two shapes every framework's refs reduce to. */
+type Ref<T> = ((node: T | null) => void) | {
+    current: T | null;
+} | null;
+
+/** Join truthy class names. Deliberately tiny — no `clsx` dependency. */
+declare function cn(...parts: Array<string | false | null | undefined>): string;
+/**
+ * A slot value that may be static or derived from live state.
+ *
+ * Every renderable field in a Pinfold config accepts both, so a caret can react to
+ * `open` without the consumer dropping down to a full slot override.
+ */
+type Slottable<State, T = unknown> = T | ((state: State) => T);
+/** Resolve a `Slottable` against the current state. */
+declare function resolveNode<State, T>(value: Slottable<State, T> | undefined, state: State): T | undefined;
+/** `data-*` attributes render when true and vanish when false. */
+declare function dataAttr(condition: unknown): '' | undefined;
+/** `aria-*` attributes want the literal strings. */
+declare function ariaAttr(condition: unknown): 'true' | undefined;
+declare function composeRefs<T>(...refs: Array<Ref<T> | undefined>): (node: T | null) => void;
+/**
+ * Merge a user props bag over ours: event handlers chain (ours first, then
+ * theirs, unless ours called `preventDefault`), `className` concatenates,
+ * `style` shallow-merges, everything else overrides.
+ */
+declare function mergeProps(base: PropsBag, overrides?: PropsBag): PropsBag;
+
+type VariantShape = Record<string, Record<string, string>>;
+type VariantProps<V extends VariantShape> = {
+    [K in keyof V]?: keyof V[K] | null | undefined;
+};
+/**
+ * 20-line class-variance resolver. Same ergonomics as `cva` without the
+ * dependency or its runtime — components are static strings plus a lookup.
+ */
+declare function variants<V extends VariantShape>(config: {
+    base?: string;
+    variants: V;
+    defaultVariants?: VariantProps<V>;
+}): (props?: VariantProps<V> & {
+    className?: string;
+}) => string;
+
+interface ListNavOptions {
+    orientation?: PinfoldOrientation;
+    dir?: PinfoldDir;
+    /** Wrap from last to first. Default true. */
+    loop?: boolean;
+}
+/**
+ * WAI-ARIA roving-focus key resolution, shared by every list-like component
+ * (accordion, tabs, menu, listbox, toolbar…).
+ *
+ * Returns the index to move focus to, or `null` when the key is not ours —
+ * callers must not `preventDefault()` on `null`.
+ */
+declare function nextIndexFromKey(key: string, current: number, count: number, { orientation, dir, loop }?: ListNavOptions): number | null;
+
+/**
+ * Turn a `dimensions` config object into CSS custom properties on the root.
+ *
+ *   dimensionVars('accordion', { paddingX: 24, panelMaxHeight: '18rem' })
+ *   // → { '--pinfold-accordion-padding-x': '24px', '--pinfold-accordion-panel-max-height': '18rem' }
+ *
+ * Numbers become px; strings pass through untouched, so `'50%'`, `'12rem'`,
+ * `'clamp(...)'` and `var(...)` all work. Every component's CSS reads these
+ * with a fallback, which is why one shared resolver covers all of them.
+ */
+declare function dimensionVars<D extends object>(component: string, dimensions: D | undefined): Record<string, string> | undefined;
+
+/**
+ * Accordion rules as pure functions. No DOM, no framework: every adapter
+ * (React today) calls these and only wires the results to its own state and
+ * events, so behaviour can never drift between adapters.
+ */
+type AccordionMode = 'single' | 'multiple';
+/** Why the open set changed. Passed to `onBeforeChange` and `onValueChange`. */
+type AccordionChangeReason = 'click' | 'keyboard' | 'api' | 'find-in-page' | 'hash';
+interface AccordionChangeDetails<E = unknown> {
+    /** The row that triggered the change. Absent for `openAll` / `closeAll`. */
+    id?: string;
+    open: boolean;
+    reason: AccordionChangeReason;
+    event?: E;
+}
+/** The minimum a row needs for the rules: its id and whether it is disabled. */
+interface AccordionRowLike {
+    id: string;
+    disabled?: boolean;
+}
+interface AccordionRules {
+    mode: AccordionMode;
+    collapsible: boolean;
+    /** Disables every row. */
+    disabled?: boolean;
+}
+/** Row id: the configured `id`, else the index as a string. */
+declare function accordionRowId(item: {
+    id?: string;
+}, index: number): string;
+/** Trigger and panel ids for a row, derived from the instance's base id. */
+declare function accordionPartIds(baseId: string, rowId: string): {
+    triggerId: string;
+    panelId: string;
+};
+/** Single mode keeps at most one open id. */
+declare function normalizeAccordionValue(value: readonly string[], mode: AccordionMode): string[];
+/** The first open set: `defaultValue` when given, else every row with `defaultOpen`. */
+declare function initialAccordionValue(items: ReadonlyArray<{
+    id?: string;
+    defaultOpen?: boolean;
+}>, defaultValue: readonly string[] | undefined, mode: AccordionMode): string[];
+/**
+ * The open set after asking row `id` to become `open`, or `null` when the
+ * rules refuse (unknown or disabled row, no change, or closing the last open
+ * row of a non-collapsible accordion, in either mode).
+ */
+declare function setAccordionItem(value: readonly string[], rows: readonly AccordionRowLike[], id: string, open: boolean, rules: AccordionRules): string[] | null;
+/** `openAll`: every enabled row, multiple mode only. */
+declare function openAllAccordion(value: readonly string[], rows: readonly AccordionRowLike[], rules: AccordionRules): string[] | null;
+/** `closeAll`: refused for a non-collapsible accordion. Disabled rows keep their state. */
+declare function closeAllAccordion(value: readonly string[], rows: readonly AccordionRowLike[], rules: AccordionRules): string[] | null;
+interface AccordionKeyOptions {
+    orientation?: PinfoldOrientation;
+    dir?: PinfoldDir;
+    loop?: boolean;
+}
+/**
+ * The header index to focus for a key, or `null` when the key is not ours.
+ * Disabled headers stay focusable (APG), so they are not skipped.
+ */
+declare function accordionFocusTarget(key: string, index: number, count: number, options?: AccordionKeyOptions): number | null;
+/**
+ * Field mapping: lets raw records (a CMS row, a DB result) feed the accordion
+ * without a `.map()`. `{ id: 'slug', title: 'question', content: 'answer' }`.
+ */
+type AccordionFieldMap<Row = any> = Partial<Record<'id' | 'title' | 'content' | 'description' | 'icon' | 'endIcon' | 'badge' | 'disabled' | 'defaultOpen', Extract<keyof Row, string>>>;
+declare function mapAccordionFields<T>(records: readonly any[], fields: AccordionFieldMap | undefined): T[];
+/**
+ * The appearance cascade, as rules every adapter and the docs share:
+ * 1. The variant decides what is a surface: the container (solid, outline), each row
+ *    (separated, filled) or nothing (ghost).
+ * 2. `radius` shapes the container; `itemRadius` defaults to it.
+ * 3. A zero gap joins the rows. Joined separated or filled rows become one group whose outer
+ *    corners follow the container `radius`; `dividers` draws the lines inside it.
+ */
+type AccordionVariantName = 'solid' | 'outline' | 'separated' | 'filled' | 'ghost';
+interface AccordionAppearanceInput {
+    variant?: AccordionVariantName;
+    /** Resolved gap: `dimensions.gap` if set, else `gap`. */
+    gap?: unknown;
+    radius?: unknown;
+    itemRadius?: unknown;
+    dividers?: boolean;
+    indicator?: unknown;
+    disabled?: boolean;
+}
+/** Whether the rows touch. The card and ghost variants default to no gap; separated and filled to a small one. */
+declare function accordionRowsJoined(variant?: AccordionVariantName, gap?: unknown): boolean;
+/**
+ * Options that have no visible effect with the rest of the config, each with the reason and
+ * what to do instead. Playgrounds disable them; the dev build warns when one is set explicitly.
+ */
+declare function inactiveAccordionOptions(input: AccordionAppearanceInput): Record<string, string>;
+/** When panel content is mounted. */
+type AccordionMountPanels = 'always' | 'open' | 'first-open';
+/** Whether a panel's content should be in the DOM right now. */
+declare function shouldMountPanel(policy: AccordionMountPanels, open: boolean, everOpened: boolean): boolean;
+
+/**
+ * Development-only diagnostics.
+ *
+ * Config-driven APIs fail quietly: a duplicated `id` or a `value` array that
+ * silently switches a component from uncontrolled to controlled produces
+ * confusing behaviour rather than an error. These warnings turn that class of
+ * mistake into a message, and vanish entirely from production builds because
+ * bundlers fold the `NODE_ENV` check.
+ */
+declare const __DEV__: boolean;
+/** Warn at most once per distinct message, so a render loop cannot spam the console. */
+declare function warnOnce(condition: unknown, message: string): void;
+/** Test hook — lets a suite assert the same warning twice. */
+declare function resetWarnings(): void;
+
+/**
+ * @pinfold/core: framework-free building blocks. Nothing here imports React or
+ * any other UI framework (enforced by `framework-isolation.test.ts`), so a
+ * future adapter reuses exactly the same rules.
+ */
+
+/** Package version, injected at publish time by the release script. */
+declare const version = "0.2.0";
+
+export { __DEV__, accordionFocusTarget, accordionPartIds, accordionRowId, accordionRowsJoined, ariaAttr, closeAllAccordion, cn, composeRefs, dataAttr, dimensionVars, inactiveAccordionOptions, initialAccordionValue, mapAccordionFields, mergeProps, nextIndexFromKey, normalizeAccordionValue, openAllAccordion, resetWarnings, resolveNode, setAccordionItem, shouldMountPanel, variants, version, warnOnce };
+export type { AccordionAppearanceInput, AccordionChangeDetails, AccordionChangeReason, AccordionFieldMap, AccordionKeyOptions, AccordionMode, AccordionMountPanels, AccordionRowLike, AccordionRules, AccordionVariantName, Length, ListNavOptions, PinfoldDir, PinfoldLazy, PinfoldOrientation, PinfoldRadius, PinfoldSize, PinfoldStylePack, PinfoldTheme, PinfoldTone, PropsBag, Ref, Slottable, VariantProps };