@stonecrop/schema 0.21.0 → 0.23.0

package/dist/index.js

@@ -1,5 +1,5 @@
-import { A as c, D as A, F as p, G as y, I as u, a as S, L as T, T as m, b as F, d as I, V as D, W as L, e as N, g as C, h as f, i as O, j as k, k as E, c as b, l as x, n as _, o as g, f as P, p as R, q as h, r as M, s as v, t as w, u as K, m as W, w as G, x as j, y as Q, z as V, B as Y, C as q, E as z, H as X, v as B, J as H } from "./validation-1DGAGmuU.js";
-const a = {
+import { A as E, D as N, F as h, G as _, I as p, a as j, L as x, T as P, b as R, d as B, V as w, W as M, e as k, g as G, h as K, i as V, j as W, k as Y, c as z, l as Q, n as q, o as J, f as X, p as H, q as U, r as Z, s as $, t as ee, u as re, m as ae, w as te, x as ne, y as ie, z as se, B as oe, C as le, E as ce, H as ue, v as de, J as fe } from "./validation-1DGAGmuU.js";
+const l = {
   ATextInput: "text",
   ATextboxInput: "text",
   ANumericInput: "number",
@@ -17,69 +17,140 @@ const a = {
   AQuantityInput: "quantity",
   ACurrencyInput: "currency"
 };
-function s(e) {
-  return e ? a[e] : void 0;
+function g(e) {
+  return e ? l[e] : void 0;
 }
-const t = {
+const c = {
   AFormLink: "inline",
   AForm: "expand",
   ATable: "expand"
 };
+function f(e) {
+  return e ? c[e] : void 0;
+}
+function v(e, r) {
+  return f(e.component ?? r) === "inline" ? "inline" : e.cardinality === "noneOrMany" || e.cardinality === "atLeastOne" ? "table" : "record";
+}
+const O = [
+  .../* @__PURE__ */ new Set([...Object.keys(l), ...Object.keys(c)])
+].toSorted(), A = /* @__PURE__ */ new Set(["neutral", "success", "warning", "danger", "brand"]), y = /* @__PURE__ */ new Set(["variant", "color", "label"]);
+function t(e) {
+  return !Array.isArray(e);
+}
 function i(e) {
-  return e ? t[e] : void 0;
+  return typeof e == "string" && A.has(e);
+}
+function u(e) {
+  if (e === null || typeof e != "object" || Array.isArray(e)) return !1;
+  for (const a of Object.keys(e))
+    if (!y.has(a)) return !1;
+  const r = e;
+  return !(r.variant !== void 0 && !i(r.variant) || r.color !== void 0 && typeof r.color != "string" || r.label !== void 0 && typeof r.label != "string");
+}
+function o(e) {
+  return i(e) || u(e);
+}
+function n(e) {
+  return Array.isArray(e.choices);
+}
+function T(e) {
+  if (e === null || typeof e != "object" || Array.isArray(e)) return !1;
+  const r = e;
+  return !(typeof r.label != "string" || r.variant !== void 0 && !i(r.variant) || r.color !== void 0 && typeof r.color != "string");
+}
+function s(e) {
+  if (e === void 0 || Array.isArray(e) || !t(e)) return !1;
+  if (n(e)) {
+    const a = e.badges;
+    return a === void 0 ? !1 : Object.values(a).every(o);
+  }
+  const r = Object.entries(e);
+  return r.length === 0 ? !1 : r.every(([, a]) => o(a));
+}
+function m(e) {
+  return e === void 0 || Array.isArray(e) || !t(e) ? !1 : n(e);
+}
+function D(e) {
+  return e === void 0 ? [] : Array.isArray(e) ? e : t(e) ? n(e) ? e.choices : s(e) ? Object.keys(e) : [] : [];
+}
+function d(e, r) {
+  return i(e) ? { label: r, variant: e } : u(e) ? {
+    label: e.label ?? r,
+    variant: e.variant,
+    color: e.color
+  } : { label: r };
+}
+function b(e, r) {
+  if (!(r === void 0 || r === "") && r in e)
+    return d(e[r], r);
+}
+function S(e, r) {
+  if (r === void 0 || r === "") return;
+  const a = e.badges;
+  if (!(!a || !(r in a)))
+    return d(a[r], r);
+}
+function F(e, r) {
+  if (!(e === void 0 || r === void 0 || r === "") && !Array.isArray(e) && t(e)) {
+    if (n(e)) return S(e, r);
+    if (s(e)) return b(e, r);
+  }
 }
-function o(e, n) {
-  return i(e.component ?? n) === "inline" ? "inline" : e.cardinality === "noneOrMany" || e.cardinality === "atLeastOne" ? "table" : "record";
+function I(e) {
+  return e === void 0 || Array.isArray(e) || !t(e) ? !1 : n(e) ? e.badges !== void 0 && Object.keys(e.badges).length > 0 : s(e);
 }
-const l = [
-  .../* @__PURE__ */ new Set([...Object.keys(a), ...Object.keys(t)])
-].toSorted();
 export {
-  c as ActionDefinition,
-  l as CANONICAL_COMPONENTS,
-  a as COMPONENT_CATEGORY,
-  t as COMPONENT_LINK_EXPANSION,
-  A as DoctypeFieldSchema,
-  p as FieldsetFieldSchema,
-  y as GQL_SCALAR_MAP,
-  u as INTERNAL_SCALARS,
-  S as INTROSPECTED_IDENTITY_PROPS,
-  T as LINK_DISPLAY_SUFFIX,
-  m as TableFieldSchema,
-  F as TableViewConfig,
-  I as TriggerDefinition,
-  D as ValueFieldSchema,
-  L as WELL_KNOWN_SCALARS,
-  N as WorkflowLayout,
-  C as WorkflowMeta,
-  f as buildScalarMap,
-  O as camelToLabel,
-  k as camelToSnake,
-  E as classifyFieldType,
-  s as componentCategory,
-  i as componentLinkExpansion,
-  b as convertGraphQLSchema,
-  x as defaultIsEntityField,
-  _ as defaultIsEntityType,
-  g as flattenFields,
-  P as formatDoctypeDrift,
-  R as getDisplayField,
-  h as getPrimaryKeyField,
-  M as getRecordIdField,
-  v as getRecordIdentity,
-  w as isActionAllowedInState,
-  K as linkDisplayFieldname,
-  W as mergeIntrospectedDoctype,
-  G as normalizeFieldKind,
-  j as parseDoctype,
-  Q as parseField,
-  V as pascalToSnake,
-  o as resolveLinkRenderMode,
-  Y as snakeToCamel,
-  q as snakeToLabel,
-  z as toPascalCase,
-  X as toSlug,
-  B as validateDoctype,
-  H as validateField
+  E as ActionDefinition,
+  O as CANONICAL_COMPONENTS,
+  l as COMPONENT_CATEGORY,
+  c as COMPONENT_LINK_EXPANSION,
+  N as DoctypeFieldSchema,
+  h as FieldsetFieldSchema,
+  _ as GQL_SCALAR_MAP,
+  p as INTERNAL_SCALARS,
+  j as INTROSPECTED_IDENTITY_PROPS,
+  x as LINK_DISPLAY_SUFFIX,
+  P as TableFieldSchema,
+  R as TableViewConfig,
+  B as TriggerDefinition,
+  w as ValueFieldSchema,
+  M as WELL_KNOWN_SCALARS,
+  k as WorkflowLayout,
+  G as WorkflowMeta,
+  K as buildScalarMap,
+  V as camelToLabel,
+  W as camelToSnake,
+  Y as classifyFieldType,
+  g as componentCategory,
+  f as componentLinkExpansion,
+  z as convertGraphQLSchema,
+  Q as defaultIsEntityField,
+  q as defaultIsEntityType,
+  J as flattenFields,
+  X as formatDoctypeDrift,
+  H as getDisplayField,
+  U as getPrimaryKeyField,
+  Z as getRecordIdField,
+  $ as getRecordIdentity,
+  I as hasBadgeOptions,
+  ee as isActionAllowedInState,
+  T as isBadgeDescriptor,
+  s as isSelectChoiceMap,
+  m as isSelectOptions,
+  re as linkDisplayFieldname,
+  F as lookupBadge,
+  ae as mergeIntrospectedDoctype,
+  te as normalizeFieldKind,
+  ne as parseDoctype,
+  ie as parseField,
+  se as pascalToSnake,
+  v as resolveLinkRenderMode,
+  D as selectChoices,
+  oe as snakeToCamel,
+  le as snakeToLabel,
+  ce as toPascalCase,
+  ue as toSlug,
+  de as validateDoctype,
+  fe as validateField
 };
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sources":["../src/component-meta.ts"],"sourcesContent":["/**\n * Semantic category for a rendering component.\n *\n * `component` is the primary field axis, so the runtime consumers that need to know what a field\n * *means* (atable cell formatting / filter widgets, record-default init) derive it from here. This\n * is the single source of \"what kind of value does this component render\", keyed by the canonical\n * registered component names — each consumer maps the category to its own concern (filter widget,\n * default value, …).\n *\n * @public\n */\nexport type ComponentCategory =\n\t'text' | 'number' | 'boolean' | 'date' | 'datetime' | 'select' | 'code' | 'link' | 'attach' | 'quantity' | 'currency'\n\n/**\n * Canonical component → semantic category. Only the components Stonecrop ships with appear here;\n * custom/unknown component names have no category and consumers fall back to their default.\n * @public\n */\nexport const COMPONENT_CATEGORY: Record<string, ComponentCategory> = {\n\tATextInput: 'text',\n\tATextboxInput: 'text',\n\tANumericInput: 'number',\n\tACheckbox: 'boolean',\n\tADate: 'date',\n\tADatePicker: 'date',\n\tADateSelection: 'date',\n\tADateTime: 'datetime',\n\tADuration: 'text',\n\tADateRange: 'date',\n\tADropdown: 'select',\n\tACodeEditor: 'code',\n\tAFormLink: 'link',\n\tAFileAttach: 'attach',\n\tAQuantityInput: 'quantity',\n\tACurrencyInput: 'currency',\n}\n\n/**\n * Resolve a component's semantic category, or `undefined` for an unknown (custom) component —\n * callers treat that as \"no opinion\" and use their own default.\n * @public\n */\nexport function componentCategory(component?: string): ComponentCategory | undefined {\n\treturn component ? COMPONENT_CATEGORY[component] : undefined\n}\n\n/**\n * Whether a link component expands its target doctype, or renders the link inline.\n *\n * This is the *only* axis the component decides. It deliberately does not choose between an\n * embedded record and an embedded table: `cardinality` states whether the value is a scalar or\n * an array, which is a fact about the data rather than a rendering preference, so a component\n * must not be able to override it (an `AForm` over a `noneOrMany` link would be handed an array\n * it cannot render). Component names encode both axes — `AFormLink`/`ATableLink` are the inline\n * pair, `AForm`/`ATable` the expanding pair — but only the inline/expand half is authoritative.\n *\n * @public\n */\nexport type LinkExpansion = 'inline' | 'expand'\n\n/**\n * Canonical link component → expansion. Only components Stonecrop ships with appear here; an\n * unmapped (custom) component has none, and callers treat that as `expand` — the behaviour that\n * predates this map, so a custom component can never silently collapse a link to a picker.\n * @public\n */\nexport const COMPONENT_LINK_EXPANSION: Record<string, LinkExpansion> = {\n\tAFormLink: 'inline',\n\tAForm: 'expand',\n\tATable: 'expand',\n}\n\n/**\n * Resolve a component's link expansion, or `undefined` for an absent/unmapped component.\n * @public\n */\nexport function componentLinkExpansion(component?: string): LinkExpansion | undefined {\n\treturn component ? COMPONENT_LINK_EXPANSION[component] : undefined\n}\n\n/**\n * How a link field renders.\n *\n * - `inline` — a scalar id-picker; the target is *not* expanded (the field keeps its own value\n *   and carries a `doctype` prop for async display-text resolution and navigation).\n * - `record` — the target doctype is resolved and embedded as a nested form.\n * - `table` — the target doctype is resolved and embedded as a child table.\n *\n * @public\n */\nexport type LinkRenderMode = 'inline' | 'record' | 'table'\n\n/**\n * Decide how a *declared* link (one with a `LinkDeclaration`) renders.\n *\n * Two independent axes: the **component** picks inline vs expand, and when expanding the\n * **cardinality** picks record vs table (many → table). The declaration's component wins over the\n * field's, matching the precedence the resolver already uses for the rendered component.\n *\n * This is the single definition of \"does this link expand\" — it is consumed by both the client\n * resolver (which builds the nested schema) and the server column builder (which must still\n * SELECT an `inline` link's FK column). Call it; never re-derive the rule at the call site, or\n * the two will drift and the client will render a table for a column the server never selected.\n *\n * @param link - the link declaration (only `component` and `cardinality` are consulted)\n * @param fieldComponent - the linked field's own `component`, used when the declaration names none\n * @public\n */\nexport function resolveLinkRenderMode(\n\tlink: { component?: string; cardinality?: string },\n\tfieldComponent?: string\n): LinkRenderMode {\n\tif (componentLinkExpansion(link.component ?? fieldComponent) === 'inline') return 'inline'\n\treturn link.cardinality === 'noneOrMany' || link.cardinality === 'atLeastOne' ? 'table' : 'record'\n}\n\n/**\n * Every component Stonecrop ships with that can render a value field, sorted by name.\n *\n * The union of the two maps above is the definition, not a copy of it: a shipped component either\n * categorises a value ({@link COMPONENT_CATEGORY}) or is one of the link containers that has no\n * value of its own ({@link COMPONENT_LINK_EXPANSION}'s `AForm`/`ATable`). `AFieldset` is absent by\n * the same rule — it is a `kind: 'fieldset'` container, so it is never a value field's component.\n *\n * `component` is an **open** axis: any string is valid, and naming a custom component is how an app\n * renders a field Stonecrop ships no widget for. This list is therefore the set to *suggest* to an\n * author, and to check first-party data against — never a set to validate arbitrary input against.\n *\n * @public\n */\nexport const CANONICAL_COMPONENTS: readonly string[] = [\n\t...new Set([...Object.keys(COMPONENT_CATEGORY), ...Object.keys(COMPONENT_LINK_EXPANSION)]),\n].toSorted()\n"],"names":["COMPONENT_CATEGORY","componentCategory","component","COMPONENT_LINK_EXPANSION","componentLinkExpansion","resolveLinkRenderMode","link","fieldComponent","CANONICAL_COMPONENTS"],"mappings":";AAmBO,MAAMA,IAAwD;AAAA,EACpE,YAAY;AAAA,EACZ,eAAe;AAAA,EACf,eAAe;AAAA,EACf,WAAW;AAAA,EACX,OAAO;AAAA,EACP,aAAa;AAAA,EACb,gBAAgB;AAAA,EAChB,WAAW;AAAA,EACX,WAAW;AAAA,EACX,YAAY;AAAA,EACZ,WAAW;AAAA,EACX,aAAa;AAAA,EACb,WAAW;AAAA,EACX,aAAa;AAAA,EACb,gBAAgB;AAAA,EAChB,gBAAgB;AACjB;AAOO,SAASC,EAAkBC,GAAmD;AACpF,SAAOA,IAAYF,EAAmBE,CAAS,IAAI;AACpD;AAsBO,MAAMC,IAA0D;AAAA,EACtE,WAAW;AAAA,EACX,OAAO;AAAA,EACP,QAAQ;AACT;AAMO,SAASC,EAAuBF,GAA+C;AACrF,SAAOA,IAAYC,EAAyBD,CAAS,IAAI;AAC1D;AA8BO,SAASG,EACfC,GACAC,GACiB;AACjB,SAAIH,EAAuBE,EAAK,aAAaC,CAAc,MAAM,WAAiB,WAC3ED,EAAK,gBAAgB,gBAAgBA,EAAK,gBAAgB,eAAe,UAAU;AAC3F;AAgBO,MAAME,IAA0C;AAAA,EACtD,GAAG,oBAAI,IAAI,CAAC,GAAG,OAAO,KAAKR,CAAkB,GAAG,GAAG,OAAO,KAAKG,CAAwB,CAAC,CAAC;AAC1F,EAAE,SAAA;"}
+{"version":3,"file":"index.js","sources":["../src/component-meta.ts","../src/badge.ts"],"sourcesContent":["/**\n * Semantic category for a rendering component.\n *\n * `component` is the primary field axis, so the runtime consumers that need to know what a field\n * *means* (atable cell formatting / filter widgets, record-default init) derive it from here. This\n * is the single source of \"what kind of value does this component render\", keyed by the canonical\n * registered component names — each consumer maps the category to its own concern (filter widget,\n * default value, …).\n *\n * @public\n */\nexport type ComponentCategory =\n\t'text' | 'number' | 'boolean' | 'date' | 'datetime' | 'select' | 'code' | 'link' | 'attach' | 'quantity' | 'currency'\n\n/**\n * Canonical component → semantic category. Only the components Stonecrop ships with appear here;\n * custom/unknown component names have no category and consumers fall back to their default.\n * @public\n */\nexport const COMPONENT_CATEGORY: Record<string, ComponentCategory> = {\n\tATextInput: 'text',\n\tATextboxInput: 'text',\n\tANumericInput: 'number',\n\tACheckbox: 'boolean',\n\tADate: 'date',\n\tADatePicker: 'date',\n\tADateSelection: 'date',\n\tADateTime: 'datetime',\n\tADuration: 'text',\n\tADateRange: 'date',\n\tADropdown: 'select',\n\tACodeEditor: 'code',\n\tAFormLink: 'link',\n\tAFileAttach: 'attach',\n\tAQuantityInput: 'quantity',\n\tACurrencyInput: 'currency',\n}\n\n/**\n * Resolve a component's semantic category, or `undefined` for an unknown (custom) component —\n * callers treat that as \"no opinion\" and use their own default.\n * @public\n */\nexport function componentCategory(component?: string): ComponentCategory | undefined {\n\treturn component ? COMPONENT_CATEGORY[component] : undefined\n}\n\n/**\n * Whether a link component expands its target doctype, or renders the link inline.\n *\n * This is the *only* axis the component decides. It deliberately does not choose between an\n * embedded record and an embedded table: `cardinality` states whether the value is a scalar or\n * an array, which is a fact about the data rather than a rendering preference, so a component\n * must not be able to override it (an `AForm` over a `noneOrMany` link would be handed an array\n * it cannot render). Component names encode both axes — `AFormLink`/`ATableLink` are the inline\n * pair, `AForm`/`ATable` the expanding pair — but only the inline/expand half is authoritative.\n *\n * @public\n */\nexport type LinkExpansion = 'inline' | 'expand'\n\n/**\n * Canonical link component → expansion. Only components Stonecrop ships with appear here; an\n * unmapped (custom) component has none, and callers treat that as `expand` — the behaviour that\n * predates this map, so a custom component can never silently collapse a link to a picker.\n * @public\n */\nexport const COMPONENT_LINK_EXPANSION: Record<string, LinkExpansion> = {\n\tAFormLink: 'inline',\n\tAForm: 'expand',\n\tATable: 'expand',\n}\n\n/**\n * Resolve a component's link expansion, or `undefined` for an absent/unmapped component.\n * @public\n */\nexport function componentLinkExpansion(component?: string): LinkExpansion | undefined {\n\treturn component ? COMPONENT_LINK_EXPANSION[component] : undefined\n}\n\n/**\n * How a link field renders.\n *\n * - `inline` — a scalar id-picker; the target is *not* expanded (the field keeps its own value\n *   and carries a `doctype` prop for async display-text resolution and navigation).\n * - `record` — the target doctype is resolved and embedded as a nested form.\n * - `table` — the target doctype is resolved and embedded as a child table.\n *\n * @public\n */\nexport type LinkRenderMode = 'inline' | 'record' | 'table'\n\n/**\n * Decide how a *declared* link (one with a `LinkDeclaration`) renders.\n *\n * Two independent axes: the **component** picks inline vs expand, and when expanding the\n * **cardinality** picks record vs table (many → table). The declaration's component wins over the\n * field's, matching the precedence the resolver already uses for the rendered component.\n *\n * This is the single definition of \"does this link expand\" — it is consumed by both the client\n * resolver (which builds the nested schema) and the server column builder (which must still\n * SELECT an `inline` link's FK column). Call it; never re-derive the rule at the call site, or\n * the two will drift and the client will render a table for a column the server never selected.\n *\n * @param link - the link declaration (only `component` and `cardinality` are consulted)\n * @param fieldComponent - the linked field's own `component`, used when the declaration names none\n * @public\n */\nexport function resolveLinkRenderMode(\n\tlink: { component?: string; cardinality?: string },\n\tfieldComponent?: string\n): LinkRenderMode {\n\tif (componentLinkExpansion(link.component ?? fieldComponent) === 'inline') return 'inline'\n\treturn link.cardinality === 'noneOrMany' || link.cardinality === 'atLeastOne' ? 'table' : 'record'\n}\n\n/**\n * Every component Stonecrop ships with that can render a value field, sorted by name.\n *\n * The union of the two maps above is the definition, not a copy of it: a shipped component either\n * categorises a value ({@link COMPONENT_CATEGORY}) or is one of the link containers that has no\n * value of its own ({@link COMPONENT_LINK_EXPANSION}'s `AForm`/`ATable`). `AFieldset` is absent by\n * the same rule — it is a `kind: 'fieldset'` container, so it is never a value field's component.\n *\n * `component` is an **open** axis: any string is valid, and naming a custom component is how an app\n * renders a field Stonecrop ships no widget for. This list is therefore the set to *suggest* to an\n * author, and to check first-party data against — never a set to validate arbitrary input against.\n *\n * @public\n */\nexport const CANONICAL_COMPONENTS: readonly string[] = [\n\t...new Set([...Object.keys(COMPONENT_CATEGORY), ...Object.keys(COMPONENT_LINK_EXPANSION)]),\n].toSorted()\n","import type { FieldOptions } from './field'\n\n/**\n * Semantic badge variant. Maps to theme tokens `--sc-badge-{variant}-*`.\n * @public\n */\nexport type BadgeVariant = 'neutral' | 'success' | 'warning' | 'danger' | 'brand'\n\n/**\n * Where ABadge paints the same descriptor.\n * @public\n */\nexport type BadgePresentation = 'cell-fill' | 'input-accent'\n\n/**\n * Per-choice badge configuration in a Select options map.\n * @public\n */\nexport interface BadgeSpecObject {\n\tvariant?: BadgeVariant\n\tcolor?: string\n\tlabel?: string\n}\n\n/**\n * Value in a choice→badge map: shorthand variant or object form.\n * @public\n */\nexport type BadgeSpec = BadgeVariant | BadgeSpecObject\n\n/**\n * Select field options when choices carry badge colors.\n * @public\n */\nexport interface SelectOptions extends Record<string, unknown> {\n\tchoices: string[]\n\tbadges?: Record<string, BadgeSpec>\n}\n\n/**\n * Resolved badge for rendering. Returned by `format` or built from an options map.\n * @public\n */\nexport interface BadgeDescriptor {\n\tlabel: string\n\tvariant?: BadgeVariant\n\tcolor?: string\n}\n\nconst BADGE_VARIANTS = new Set<string>(['neutral', 'success', 'warning', 'danger', 'brand'])\n\nconst BADGE_SPEC_OBJECT_KEYS = new Set(['variant', 'color', 'label'])\n\nfunction isOptionsRecord(options: FieldOptions): options is Record<string, unknown> {\n\treturn !Array.isArray(options)\n}\n\nfunction isBadgeVariant(value: unknown): value is BadgeVariant {\n\treturn typeof value === 'string' && BADGE_VARIANTS.has(value)\n}\n\nfunction isBadgeSpecObject(value: unknown): value is BadgeSpecObject {\n\tif (value === null || typeof value !== 'object' || Array.isArray(value)) return false\n\tfor (const key of Object.keys(value)) {\n\t\tif (!BADGE_SPEC_OBJECT_KEYS.has(key)) return false\n\t}\n\tconst obj = value as BadgeSpecObject\n\tif (obj.variant !== undefined && !isBadgeVariant(obj.variant)) return false\n\tif (obj.color !== undefined && typeof obj.color !== 'string') return false\n\tif (obj.label !== undefined && typeof obj.label !== 'string') return false\n\treturn true\n}\n\nfunction isBadgeSpec(value: unknown): value is BadgeSpec {\n\treturn isBadgeVariant(value) || isBadgeSpecObject(value)\n}\n\n/**\n * Narrows an options record to the structured `{ choices, badges }` form. A type predicate rather\n * than a cast: `SelectOptions` requires `choices`, so asserting into it trips `no-unsafe-type-assertion`.\n */\nfunction isStructuredSelectOptions(options: Record<string, unknown>): options is SelectOptions {\n\treturn Array.isArray(options.choices)\n}\n\n/**\n * True when `value` is a resolved badge descriptor for ACell / ADropdown.\n * @public\n */\nexport function isBadgeDescriptor(value: unknown): value is BadgeDescriptor {\n\tif (value === null || typeof value !== 'object' || Array.isArray(value)) return false\n\t// Partial<> keeps this a widening assertion; asserting into BadgeDescriptor itself (required\n\t// `label`) narrows, which `no-unsafe-type-assertion` rejects.\n\tconst obj = value as Partial<BadgeDescriptor>\n\tif (typeof obj.label !== 'string') return false\n\tif (obj.variant !== undefined && !isBadgeVariant(obj.variant)) return false\n\tif (obj.color !== undefined && typeof obj.color !== 'string') return false\n\treturn true\n}\n\n/**\n * True when `options` is a Select choice map (`{ Open: \"warning\", ... }` or\n * `{ choices: [...], badges: {...} }`), not a quantity/currency/code config bag.\n * @public\n */\nexport function isSelectChoiceMap(options: FieldOptions | undefined): options is Record<string, BadgeSpec> {\n\tif (options === undefined || Array.isArray(options) || !isOptionsRecord(options)) return false\n\tif (isStructuredSelectOptions(options)) {\n\t\tconst badges = options.badges\n\t\tif (badges === undefined) return false\n\t\treturn Object.values(badges).every(isBadgeSpec)\n\t}\n\tconst entries = Object.entries(options)\n\tif (entries.length === 0) return false\n\treturn entries.every(([, value]) => isBadgeSpec(value))\n}\n\n/**\n * True when `options` uses the structured SelectOptions shape.\n * @public\n */\nexport function isSelectOptions(options: FieldOptions | undefined): options is SelectOptions {\n\tif (options === undefined || Array.isArray(options) || !isOptionsRecord(options)) return false\n\treturn isStructuredSelectOptions(options)\n}\n\n/**\n * Dropdown / filter choice strings.\n * @public\n */\nexport function selectChoices(options: FieldOptions | undefined): string[] {\n\tif (options === undefined) return []\n\tif (Array.isArray(options)) return options\n\tif (!isOptionsRecord(options)) return []\n\tif (isStructuredSelectOptions(options)) return options.choices\n\tif (isSelectChoiceMap(options)) return Object.keys(options)\n\treturn []\n}\n\nfunction normalizeBadgeSpec(spec: unknown, key: string): BadgeDescriptor {\n\tif (isBadgeVariant(spec)) {\n\t\treturn { label: key, variant: spec }\n\t}\n\t// A malformed spec still names a real choice, so keep the label and drop only the styling.\n\t// Reading `.variant`/`.color` off an unvalidated value is what let a misspelt variant reach the\n\t// DOM as an unmatched class, and threw outright on null.\n\tif (!isBadgeSpecObject(spec)) {\n\t\treturn { label: key }\n\t}\n\treturn {\n\t\tlabel: spec.label ?? key,\n\t\tvariant: spec.variant,\n\t\tcolor: spec.color,\n\t}\n}\n\nfunction lookupFromBareMap(map: Record<string, BadgeSpec>, key: string | undefined): BadgeDescriptor | undefined {\n\tif (key === undefined || key === '') return undefined\n\tif (!(key in map)) return undefined\n\treturn normalizeBadgeSpec(map[key], key)\n}\n\nfunction lookupFromStructured(options: SelectOptions, key: string | undefined): BadgeDescriptor | undefined {\n\tif (key === undefined || key === '') return undefined\n\tconst badges = options.badges\n\tif (!badges || !(key in badges)) return undefined\n\treturn normalizeBadgeSpec(badges[key], key)\n}\n\n/**\n * Resolve a stored choice value to a badge descriptor using field options.\n * @public\n */\nexport function lookupBadge(options: FieldOptions | undefined, key: string | undefined): BadgeDescriptor | undefined {\n\tif (options === undefined || key === undefined || key === '') return undefined\n\tif (Array.isArray(options)) return undefined\n\tif (!isOptionsRecord(options)) return undefined\n\tif (isStructuredSelectOptions(options)) return lookupFromStructured(options, key)\n\tif (isSelectChoiceMap(options)) return lookupFromBareMap(options, key)\n\treturn undefined\n}\n\n/**\n * Whether field options carry any badge mapping.\n * @public\n */\nexport function hasBadgeOptions(options: FieldOptions | undefined): boolean {\n\tif (options === undefined || Array.isArray(options)) return false\n\tif (!isOptionsRecord(options)) return false\n\tif (isStructuredSelectOptions(options)) return options.badges !== undefined && Object.keys(options.badges).length > 0\n\treturn isSelectChoiceMap(options)\n}\n"],"names":["COMPONENT_CATEGORY","componentCategory","component","COMPONENT_LINK_EXPANSION","componentLinkExpansion","resolveLinkRenderMode","link","fieldComponent","CANONICAL_COMPONENTS","BADGE_VARIANTS","BADGE_SPEC_OBJECT_KEYS","isOptionsRecord","options","isBadgeVariant","value","isBadgeSpecObject","key","obj","isBadgeSpec","isStructuredSelectOptions","isBadgeDescriptor","isSelectChoiceMap","badges","entries","isSelectOptions","selectChoices","normalizeBadgeSpec","spec","lookupFromBareMap","map","lookupFromStructured","lookupBadge","hasBadgeOptions"],"mappings":"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"}

package/dist/schema.d.ts

@@ -32,6 +32,44 @@ export declare type ActionDefinition = z.infer<typeof ActionDefinition>;
  */
 export declare type AuthoredDoctype = Record<string, unknown>;
 
+/**
+ * Resolved badge for rendering. Returned by `format` or built from an options map.
+ * @public
+ */
+export declare interface BadgeDescriptor {
+    label: string;
+    variant?: BadgeVariant;
+    color?: string;
+}
+
+/**
+ * Where ABadge paints the same descriptor.
+ * @public
+ */
+export declare type BadgePresentation = 'cell-fill' | 'input-accent';
+
+/**
+ * Value in a choice→badge map: shorthand variant or object form.
+ * @public
+ */
+export declare type BadgeSpec = BadgeVariant | BadgeSpecObject;
+
+/**
+ * Per-choice badge configuration in a Select options map.
+ * @public
+ */
+export declare interface BadgeSpecObject {
+    variant?: BadgeVariant;
+    color?: string;
+    label?: string;
+}
+
+/**
+ * Semantic badge variant. Maps to theme tokens `--sc-badge-{variant}-*`.
+ * @public
+ */
+export declare type BadgeVariant = 'neutral' | 'success' | 'warning' | 'danger' | 'brand';
+
 /**
  * Build a merged scalar map from the built-in maps and user-provided custom scalars.
  * Precedence (highest to lowest): customScalars → GQL_SCALAR_MAP → WELL_KNOWN_SCALARS
@@ -247,10 +285,15 @@ export declare interface ColumnSchema {
      * Only applicable when `modalComponent` is set.
      */
     modalComponentExtraProps?: Record<string, any>;
+    /**
+     * Type-specific field options — Select choices, badge maps, quantity/currency config, etc.
+     * Spreads through `schemaToColumns` to `TableColumn`.
+     */
+    options?: FieldOptions;
     /**
      * Serialized function string used to format the cell value for display. Deserialized at
-     * render time by the table store's `getFormattedValue`. `TableColumn.format` widens this
-     * to also accept a live function directly.
+     * render time by the table store's `getFormattedValue`. May return a plain string, HTML, or a
+     * {@link BadgeDescriptor}. `TableColumn.format` widens this to also accept a live function.
      */
     format?: string;
     /**
@@ -632,6 +675,7 @@ export declare type FetchStrategy = z.infer<typeof FetchStrategy>;
  *
  * Usage:
  * - Select: array of choices (["Draft", "Submitted", "Cancelled"])
+ * - Select with badges: \{ choices: [...], badges: \{ Open: "warning", ... \} \} or bare map
  * - Decimal: config object (\{ precision: 10, scale: 2 \})
  * - Code: config object (\{ language: "python" \})
  *
@@ -1022,6 +1066,12 @@ export declare interface GraphQLConversionOptions {
     includeUnmappedMeta?: boolean;
 }
 
+/**
+ * Whether field options carry any badge mapping.
+ * @public
+ */
+export declare function hasBadgeOptions(options: FieldOptions | undefined): boolean;
+
 /**
  * Controls the level of user interaction for a field, container, or table.
  *
@@ -1089,6 +1139,25 @@ export declare function isActionAllowedInState(action: {
     allowedStates?: string[] | null;
 }, currentState: string): boolean;
 
+/**
+ * True when `value` is a resolved badge descriptor for ACell / ADropdown.
+ * @public
+ */
+export declare function isBadgeDescriptor(value: unknown): value is BadgeDescriptor;
+
+/**
+ * True when `options` is a Select choice map (`{ Open: "warning", ... }` or
+ * `{ choices: [...], badges: {...} }`), not a quantity/currency/code config bag.
+ * @public
+ */
+export declare function isSelectChoiceMap(options: FieldOptions | undefined): options is Record<string, BadgeSpec>;
+
+/**
+ * True when `options` uses the structured SelectOptions shape.
+ * @public
+ */
+export declare function isSelectOptions(options: FieldOptions | undefined): options is SelectOptions;
+
 /**
  * Lazy fetch strategy - data is fetched on demand in a separate query.
  * @public
@@ -1182,6 +1251,12 @@ export declare type LinkExpansion = 'inline' | 'expand';
  */
 export declare type LinkRenderMode = 'inline' | 'record' | 'table';
 
+/**
+ * Resolve a stored choice value to a badge descriptor using field options.
+ * @public
+ */
+export declare function lookupBadge(options: FieldOptions | undefined, key: string | undefined): BadgeDescriptor | undefined;
+
 /**
  * Verify an authored doctype against freshly generated output and stamp provenance.
  *
@@ -1277,6 +1352,21 @@ export declare function resolveLinkRenderMode(link: {
     cardinality?: string;
 }, fieldComponent?: string): LinkRenderMode;
 
+/**
+ * Dropdown / filter choice strings.
+ * @public
+ */
+export declare function selectChoices(options: FieldOptions | undefined): string[];
+
+/**
+ * Select field options when choices carry badge colors.
+ * @public
+ */
+export declare interface SelectOptions extends Record<string, unknown> {
+    choices: string[];
+    badges?: Record<string, BadgeSpec>;
+}
+
 /**
  * Serialized function type - a function serialized to a string.
  * Used for custom fetch handlers.
@@ -1539,9 +1629,10 @@ export declare interface ValueField {
     edit?: boolean;
     /** Input mask pattern or serialized function */
     mask?: string;
-    /** Serialized `(value) => string` function for display formatting — distinct from `mask` (input).
-     *  Spreads through `schemaToColumns` to `ColumnSchema.format`; deserialized at render time by
-     *  ATable's `getFormattedValue`. */
+    /** Serialized display formatter — distinct from `mask` (input). Spreads through
+     *  `schemaToColumns` to `ColumnSchema.format`; deserialized at render time by ATable's
+     *  `getFormattedValue`. Returns a plain string, HTML, or a {@link BadgeDescriptor} for badge
+     *  cells. When a descriptor is returned it wins over any badge map on `options`. */
     format?: string;
     /** Per-field interaction mode override */
     mode?: InteractionMode;

package/dist/src/badge.d.ts

@@ -0,0 +1,74 @@
+import type { FieldOptions } from './field';
+/**
+ * Semantic badge variant. Maps to theme tokens `--sc-badge-{variant}-*`.
+ * @public
+ */
+export type BadgeVariant = 'neutral' | 'success' | 'warning' | 'danger' | 'brand';
+/**
+ * Where ABadge paints the same descriptor.
+ * @public
+ */
+export type BadgePresentation = 'cell-fill' | 'input-accent';
+/**
+ * Per-choice badge configuration in a Select options map.
+ * @public
+ */
+export interface BadgeSpecObject {
+    variant?: BadgeVariant;
+    color?: string;
+    label?: string;
+}
+/**
+ * Value in a choice→badge map: shorthand variant or object form.
+ * @public
+ */
+export type BadgeSpec = BadgeVariant | BadgeSpecObject;
+/**
+ * Select field options when choices carry badge colors.
+ * @public
+ */
+export interface SelectOptions extends Record<string, unknown> {
+    choices: string[];
+    badges?: Record<string, BadgeSpec>;
+}
+/**
+ * Resolved badge for rendering. Returned by `format` or built from an options map.
+ * @public
+ */
+export interface BadgeDescriptor {
+    label: string;
+    variant?: BadgeVariant;
+    color?: string;
+}
+/**
+ * True when `value` is a resolved badge descriptor for ACell / ADropdown.
+ * @public
+ */
+export declare function isBadgeDescriptor(value: unknown): value is BadgeDescriptor;
+/**
+ * True when `options` is a Select choice map (`{ Open: "warning", ... }` or
+ * `{ choices: [...], badges: {...} }`), not a quantity/currency/code config bag.
+ * @public
+ */
+export declare function isSelectChoiceMap(options: FieldOptions | undefined): options is Record<string, BadgeSpec>;
+/**
+ * True when `options` uses the structured SelectOptions shape.
+ * @public
+ */
+export declare function isSelectOptions(options: FieldOptions | undefined): options is SelectOptions;
+/**
+ * Dropdown / filter choice strings.
+ * @public
+ */
+export declare function selectChoices(options: FieldOptions | undefined): string[];
+/**
+ * Resolve a stored choice value to a badge descriptor using field options.
+ * @public
+ */
+export declare function lookupBadge(options: FieldOptions | undefined, key: string | undefined): BadgeDescriptor | undefined;
+/**
+ * Whether field options carry any badge mapping.
+ * @public
+ */
+export declare function hasBadgeOptions(options: FieldOptions | undefined): boolean;
+//# sourceMappingURL=badge.d.ts.map

package/dist/src/badge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"badge.d.ts","sourceRoot":"","sources":["../../src/badge.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,SAAS,CAAA;AAE3C;;;GAGG;AACH,MAAM,MAAM,YAAY,GAAG,SAAS,GAAG,SAAS,GAAG,SAAS,GAAG,QAAQ,GAAG,OAAO,CAAA;AAEjF;;;GAGG;AACH,MAAM,MAAM,iBAAiB,GAAG,WAAW,GAAG,cAAc,CAAA;AAE5D;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC/B,OAAO,CAAC,EAAE,YAAY,CAAA;IACtB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,KAAK,CAAC,EAAE,MAAM,CAAA;CACd;AAED;;;GAGG;AACH,MAAM,MAAM,SAAS,GAAG,YAAY,GAAG,eAAe,CAAA;AAEtD;;;GAGG;AACH,MAAM,WAAW,aAAc,SAAQ,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAC7D,OAAO,EAAE,MAAM,EAAE,CAAA;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAA;CAClC;AAED;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC/B,KAAK,EAAE,MAAM,CAAA;IACb,OAAO,CAAC,EAAE,YAAY,CAAA;IACtB,KAAK,CAAC,EAAE,MAAM,CAAA;CACd;AAsCD;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,eAAe,CAS1E;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,YAAY,GAAG,SAAS,GAAG,OAAO,IAAI,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAUzG;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,YAAY,GAAG,SAAS,GAAG,OAAO,IAAI,aAAa,CAG3F;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,YAAY,GAAG,SAAS,GAAG,MAAM,EAAE,CAOzE;AAgCD;;;GAGG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,YAAY,GAAG,SAAS,EAAE,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,eAAe,GAAG,SAAS,CAOnH;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,YAAY,GAAG,SAAS,GAAG,OAAO,CAK1E"}

package/dist/src/badge.js

@@ -0,0 +1,158 @@
+const BADGE_VARIANTS = new Set(['neutral', 'success', 'warning', 'danger', 'brand']);
+const BADGE_SPEC_OBJECT_KEYS = new Set(['variant', 'color', 'label']);
+function isOptionsRecord(options) {
+    return !Array.isArray(options);
+}
+function isBadgeVariant(value) {
+    return typeof value === 'string' && BADGE_VARIANTS.has(value);
+}
+function isBadgeSpecObject(value) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    for (const key of Object.keys(value)) {
+        if (!BADGE_SPEC_OBJECT_KEYS.has(key))
+            return false;
+    }
+    const obj = value;
+    if (obj.variant !== undefined && !isBadgeVariant(obj.variant))
+        return false;
+    if (obj.color !== undefined && typeof obj.color !== 'string')
+        return false;
+    if (obj.label !== undefined && typeof obj.label !== 'string')
+        return false;
+    return true;
+}
+function isBadgeSpec(value) {
+    return isBadgeVariant(value) || isBadgeSpecObject(value);
+}
+/**
+ * Narrows an options record to the structured `{ choices, badges }` form. A type predicate rather
+ * than a cast: `SelectOptions` requires `choices`, so asserting into it trips `no-unsafe-type-assertion`.
+ */
+function isStructuredSelectOptions(options) {
+    return Array.isArray(options.choices);
+}
+/**
+ * True when `value` is a resolved badge descriptor for ACell / ADropdown.
+ * @public
+ */
+export function isBadgeDescriptor(value) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    // Partial<> keeps this a widening assertion; asserting into BadgeDescriptor itself (required
+    // `label`) narrows, which `no-unsafe-type-assertion` rejects.
+    const obj = value;
+    if (typeof obj.label !== 'string')
+        return false;
+    if (obj.variant !== undefined && !isBadgeVariant(obj.variant))
+        return false;
+    if (obj.color !== undefined && typeof obj.color !== 'string')
+        return false;
+    return true;
+}
+/**
+ * True when `options` is a Select choice map (`{ Open: "warning", ... }` or
+ * `{ choices: [...], badges: {...} }`), not a quantity/currency/code config bag.
+ * @public
+ */
+export function isSelectChoiceMap(options) {
+    if (options === undefined || Array.isArray(options) || !isOptionsRecord(options))
+        return false;
+    if (isStructuredSelectOptions(options)) {
+        const badges = options.badges;
+        if (badges === undefined)
+            return false;
+        return Object.values(badges).every(isBadgeSpec);
+    }
+    const entries = Object.entries(options);
+    if (entries.length === 0)
+        return false;
+    return entries.every(([, value]) => isBadgeSpec(value));
+}
+/**
+ * True when `options` uses the structured SelectOptions shape.
+ * @public
+ */
+export function isSelectOptions(options) {
+    if (options === undefined || Array.isArray(options) || !isOptionsRecord(options))
+        return false;
+    return isStructuredSelectOptions(options);
+}
+/**
+ * Dropdown / filter choice strings.
+ * @public
+ */
+export function selectChoices(options) {
+    if (options === undefined)
+        return [];
+    if (Array.isArray(options))
+        return options;
+    if (!isOptionsRecord(options))
+        return [];
+    if (isStructuredSelectOptions(options))
+        return options.choices;
+    if (isSelectChoiceMap(options))
+        return Object.keys(options);
+    return [];
+}
+function normalizeBadgeSpec(spec, key) {
+    if (isBadgeVariant(spec)) {
+        return { label: key, variant: spec };
+    }
+    // A malformed spec still names a real choice, so keep the label and drop only the styling.
+    // Reading `.variant`/`.color` off an unvalidated value is what let a misspelt variant reach the
+    // DOM as an unmatched class, and threw outright on null.
+    if (!isBadgeSpecObject(spec)) {
+        return { label: key };
+    }
+    return {
+        label: spec.label ?? key,
+        variant: spec.variant,
+        color: spec.color,
+    };
+}
+function lookupFromBareMap(map, key) {
+    if (key === undefined || key === '')
+        return undefined;
+    if (!(key in map))
+        return undefined;
+    return normalizeBadgeSpec(map[key], key);
+}
+function lookupFromStructured(options, key) {
+    if (key === undefined || key === '')
+        return undefined;
+    const badges = options.badges;
+    if (!badges || !(key in badges))
+        return undefined;
+    return normalizeBadgeSpec(badges[key], key);
+}
+/**
+ * Resolve a stored choice value to a badge descriptor using field options.
+ * @public
+ */
+export function lookupBadge(options, key) {
+    if (options === undefined || key === undefined || key === '')
+        return undefined;
+    if (Array.isArray(options))
+        return undefined;
+    if (!isOptionsRecord(options))
+        return undefined;
+    if (isStructuredSelectOptions(options))
+        return lookupFromStructured(options, key);
+    if (isSelectChoiceMap(options))
+        return lookupFromBareMap(options, key);
+    return undefined;
+}
+/**
+ * Whether field options carry any badge mapping.
+ * @public
+ */
+export function hasBadgeOptions(options) {
+    if (options === undefined || Array.isArray(options))
+        return false;
+    if (!isOptionsRecord(options))
+        return false;
+    if (isStructuredSelectOptions(options))
+        return options.badges !== undefined && Object.keys(options.badges).length > 0;
+    return isSelectChoiceMap(options);
+}