@aglyn/besigner-ui 1.0.0-beta.143

package/src/lib/utils/theme-scale-options.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../../libs/besigner/feature/designer/src/lib/utils/theme-scale-options.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport type {\n  PresetChoiceOption,\n  ThemeScaleOption,\n} from '@aglyn/shared-ui-jsx-forms'\n\n/**\n * The theme scales the styles panel offers for Font Size, Font Weight and\n * Z-Index (AGL-2486, item 12).\n *\n * Every option's `value` is a token path MUI's sx system resolves ITSELF —\n * `fontSize` and `fontWeight` are declared with `themeKey: 'typography'` and\n * `zIndex` with `themeKey: 'zIndex'`, so `h4.fontSize`, `fontWeightBold` and\n * `appBar` behave exactly like `color: 'primary.main'` does. Nothing new has\n * to resolve them and nothing downstream has to know these lists exist: the\n * panel stores a string, the theme turns it into a number.\n *\n * They are built from the SITE theme rather than hardcoded, so a host that\n * has retuned its type scale or added a z-index layer offers its own values,\n * and the `hint` on each option is read out of that theme too — which is the\n * only thing that makes `h4.fontSize` legible to an author.\n */\n\n/** The subset of a theme these builders read. */\nexport interface ThemeScaleSource {\n  typography?: Record<string, unknown>\n  zIndex?: Record<string, unknown>\n  /** A created theme exposes `spacing` as a FUNCTION (`spacing(2)` →\n   * `'16px'`); raw theme options carry the bare unit number. Both are\n   * accepted because both reach these builders. */\n  spacing?: ((factor: number) => string | number) | number\n  /** `shape.borderRadius` — the unit a bare `borderRadius` number multiplies. */\n  shape?: { borderRadius?: number | string }\n  /** `theme.shadows`, MUI's 25-entry elevation ladder. */\n  shadows?: ReadonlyArray<string>\n}\n\n/** `mobileStepper` → `Mobile stepper`. */\nfunction humanizeKey(key: string): string {\n  const spaced = key\n    .replace(/([a-z0-9])([A-Z])/g, '$1 $2')\n    .replace(/[-_]+/g, ' ')\n    .trim()\n    .toLowerCase()\n  return spaced.charAt(0).toUpperCase() + spaced.slice(1)\n}\n\n/** What a theme value reads as in the hint, or '' when it is not a scalar. */\nfunction hintOf(value: unknown): string {\n  if (typeof value === 'number') return Number.isFinite(value) ? `${value}` : ''\n  return typeof value === 'string' ? value : ''\n}\n\n/**\n * The typography variants offered as font sizes, in the order a type scale\n * is read rather than alphabetically. A variant the theme does not define —\n * or defines without a `fontSize` — is dropped, so a slimmed-down host theme\n * offers only what it really has.\n */\nconst FONT_SIZE_VARIANTS: ReadonlyArray<{ key: string; label: string }> = [\n  { key: 'h1', label: 'Heading 1' },\n  { key: 'h2', label: 'Heading 2' },\n  { key: 'h3', label: 'Heading 3' },\n  { key: 'h4', label: 'Heading 4' },\n  { key: 'h5', label: 'Heading 5' },\n  { key: 'h6', label: 'Heading 6' },\n  { key: 'subtitle1', label: 'Subtitle 1' },\n  { key: 'subtitle2', label: 'Subtitle 2' },\n  { key: 'body1', label: 'Body' },\n  { key: 'body2', label: 'Body small' },\n  { key: 'button', label: 'Button' },\n  { key: 'caption', label: 'Caption' },\n  { key: 'overline', label: 'Overline' },\n]\n\n/**\n * Every variant the theme defines, not just the ones MUI ships (AGL-2486).\n *\n * The list above names MUI's own variants in reading order; a host that adds\n * rungs of its own — Aglyn's theme carries `lede`, `bodyCompact` and `micro`\n * for the 17/13/11px steps MUI has no name for — is unreachable from a fixed\n * list, which leaves an author typing the pixels. Discovering the extras keeps\n * the curated order for the familiar ones and appends whatever else the host\n * defined, sorted small to large so the ramp still reads.\n *\n * A variant is anything under `theme.typography` that is an OBJECT carrying a\n * `fontSize`; that skips `fontFamily`, the `fontWeight*` scalars and\n * `pxToRem` without naming them.\n */\nfunction themeTypographyVariants(\n  typography: Record<string, unknown> | undefined,\n): Array<{ key: string; label: string }> {\n  if (!typography) return []\n  const known = new Set(FONT_SIZE_VARIANTS.map((entry) => entry.key))\n  const extra: Array<{ key: string; label: string; size: number }> = []\n  for (const key of Object.keys(typography)) {\n    if (known.has(key)) continue\n    const value = typography[key]\n    if (!value || typeof value !== 'object') continue\n    const size = (value as Record<string, unknown>).fontSize\n    const parsed = Number.parseFloat(String(size ?? ''))\n    if (!Number.isFinite(parsed)) continue\n    extra.push({ key, label: humanizeKey(key), size: parsed })\n  }\n  extra.sort((a, b) => a.size - b.size)\n  return [...FONT_SIZE_VARIANTS, ...extra.map(({ key, label }) => ({ key, label }))]\n}\n\n/** Font sizes from `theme.typography`, e.g. `h4.fontSize` → `2.125rem`. */\nexport function buildFontSizeScaleOptions(\n  theme: ThemeScaleSource | undefined,\n): ThemeScaleOption[] {\n  const typography = theme?.typography\n  if (!typography) return []\n  const options: ThemeScaleOption[] = []\n  for (const { key, label } of themeTypographyVariants(typography)) {\n    const variant = typography[key]\n    if (!variant || typeof variant !== 'object') continue\n    const fontSize = (variant as Record<string, unknown>)['fontSize']\n    const hint = hintOf(fontSize)\n    if (!hint) continue\n    options.push({ value: `${key}.fontSize`, label, hint })\n  }\n  return options\n}\n\n/**\n * The four weights MUI's typography names, then the plain CSS ladder.\n *\n * Both halves are offered because both are real answers: `fontWeightBold`\n * follows a host that decides its bold is 600, while `700` is what an author\n * who wants exactly 700 means. The token entries come first so the\n * theme-following answer is the one in reach.\n */\n/**\n * Weight tokens are DISCOVERED, not listed (AGL-2486).\n *\n * Hardcoding MUI's four defaults would hide every weight a host adds to its\n * own ramp — Aglyn's theme carries SemiBold 600, ExtraBold 800 and Black 900 —\n * leaving a raw number as the only way to reach the brand's own weight.\n * Reading the keys off `theme.typography` means any host's ramp shows up with\n * no edit here.\n *\n * Ordered by the weight each resolves to, so the menu reads light → heavy\n * rather than in whatever order the theme object happened to be written.\n */\nconst FONT_WEIGHT_KEY = /^fontWeight(.+)$/\n\nfunction themeFontWeightTokens(\n  typography: Record<string, unknown> | undefined,\n): Array<{ key: string; label: string; weight: number }> {\n  if (!typography) return []\n  const found: Array<{ key: string; label: string; weight: number }> = []\n  for (const key of Object.keys(typography)) {\n    const match = FONT_WEIGHT_KEY.exec(key)\n    if (!match) continue\n    const raw = typography[key]\n    const weight =\n      typeof raw === 'number' ? raw : Number.parseFloat(String(raw ?? ''))\n    if (!Number.isFinite(weight)) continue\n    found.push({ key, label: `${humanizeKey(match[1])} (theme)`, weight })\n  }\n  return found.sort((a, b) => a.weight - b.weight)\n}\n\nconst FONT_WEIGHT_LADDER: ReadonlyArray<{ value: string; label: string }> = [\n  { value: '100', label: 'Thin' },\n  { value: '200', label: 'Extra light' },\n  { value: '300', label: 'Light' },\n  { value: '400', label: 'Regular' },\n  { value: '500', label: 'Medium' },\n  { value: '600', label: 'Semi bold' },\n  { value: '700', label: 'Bold' },\n  { value: '800', label: 'Extra bold' },\n  { value: '900', label: 'Black' },\n]\n\nexport function buildFontWeightScaleOptions(\n  theme: ThemeScaleSource | undefined,\n): ThemeScaleOption[] {\n  const typography = theme?.typography\n  const options: ThemeScaleOption[] = []\n  for (const { key, label } of themeFontWeightTokens(typography)) {\n    const hint = hintOf(typography ? typography[key] : undefined)\n    if (!hint) continue\n    options.push({ value: key, label, hint })\n  }\n  for (const entry of FONT_WEIGHT_LADDER) {\n    options.push({ value: entry.value, label: entry.label, hint: entry.value })\n  }\n  return options\n}\n\n/**\n * Stacking layers from `theme.zIndex`, ordered by the layer they sit on\n * rather than alphabetically — an author picking \"above the app bar\" is\n * reading the stack, not the key names.\n *\n * This is the one of the three where a raw number is usually the WRONG\n * answer: typing `1300` next to a modal the theme also puts at 1300 is a\n * coin toss, and a host that re-tunes its layers leaves that number behind.\n */\nexport function buildZIndexScaleOptions(\n  theme: ThemeScaleSource | undefined,\n): ThemeScaleOption[] {\n  const zIndex = theme?.zIndex\n  if (!zIndex) return []\n  return Object.keys(zIndex)\n    .filter((key) => typeof zIndex[key] === 'number')\n    .sort((a, b) => (zIndex[a] as number) - (zIndex[b] as number))\n    .map((key) => ({\n      value: key,\n      label: humanizeKey(key),\n      hint: `${zIndex[key]}`,\n    }))\n}\n\n/* ── Spacing ──────────────────────────────────────────────────────────── */\n\n/**\n * One rung of the theme's spacing ladder, as the box styler offers it\n * (AGL-2486, item 5).\n *\n * **`value` is a NUMBER and that is the whole point.** MUI's sx system\n * resolves a bare number on a spacing property through `theme.spacing`, so\n * `marginTop: 2` renders 16px under `spacing: 8` and 8px under `spacing: 4`\n * — it keeps following the theme exactly the way `h4.fontSize` and\n * `primary.main` do. Storing the resolved `'16px'` instead would be wrong\n * for the same reason a flattened colour is wrong: it stops tracking the\n * theme the moment anyone retunes it.\n *\n * The numeric form is also the ONLY one that works. MUI multiplies numbers\n * and passes strings through untouched, so the string `'2'` would reach the\n * browser as `margin-top: 2` and be dropped by the CSS parser.\n */\nexport interface SpacingScaleOption {\n  /** The theme spacing STEP, stored as a number so MUI resolves it. */\n  value: number\n  /** The author's name for it (`Medium`) — no CSS vocabulary required. */\n  label: string\n  /** What it resolves to in this theme today (`16px`). */\n  hint: string\n}\n\n/**\n * The ladder offered, in the order a scale is read.\n *\n * Named rather than numbered because this is the one control in the panel\n * a non-developer is guaranteed to meet: \"Medium\" is a choice anyone can\n * make, \"2\" is a question about what the unit is. The resolved value rides\n * along in the hint so the answer is still there for whoever wants it.\n *\n * `0` is on the ladder as **None**, and it is a real value meaning \"no\n * space\", not the absence of one — the styler keeps \"not set\" as a separate\n * answer that removes the property entirely.\n */\nconst SPACING_STEPS: ReadonlyArray<{ step: number; label: string }> = [\n  { step: 0, label: 'None' },\n  { step: 0.5, label: 'Hairline' },\n  { step: 1, label: 'Extra small' },\n  { step: 2, label: 'Small' },\n  { step: 3, label: 'Medium' },\n  { step: 4, label: 'Large' },\n  { step: 6, label: 'Extra large' },\n  { step: 8, label: 'Huge' },\n  { step: 12, label: 'Giant' },\n]\n\n/** What one step resolves to, or `''` when the theme cannot answer. */\nfunction resolveSpacing(\n  spacing: ThemeScaleSource['spacing'],\n  step: number,\n): string {\n  if (typeof spacing === 'function') {\n    const resolved = spacing(step)\n    if (typeof resolved === 'number') {\n      return Number.isFinite(resolved) ? `${resolved}px` : ''\n    }\n    return typeof resolved === 'string' ? resolved : ''\n  }\n  // Raw theme options carry the bare unit; mirror MUI's own arithmetic.\n  if (typeof spacing === 'number' && Number.isFinite(spacing)) {\n    return `${spacing * step}px`\n  }\n  return ''\n}\n\n/**\n * The spacing ladder read off the SITE theme, so a host that set\n * `spacing: 4` offers its own eight-step ladder rather than Aglyn's.\n *\n * A theme with no usable `spacing` yields an empty list, which leaves the\n * styler on custom amounts only — never a ladder of numbers that resolve to\n * nothing.\n */\nexport function buildSpacingScaleOptions(\n  theme: ThemeScaleSource | undefined,\n): SpacingScaleOption[] {\n  const spacing = theme?.spacing\n  const options: SpacingScaleOption[] = []\n  for (const { step, label } of SPACING_STEPS) {\n    const hint = resolveSpacing(spacing, step)\n    // `'0px'` is truthy, so None survives this guard — the check is for a\n    // theme that cannot resolve the step at all, not for a zero value.\n    if (hint === '') continue\n    options.push({ value: step, label, hint })\n  }\n  return options\n}\n\n/** Every theme scale the style field groups need, built once per theme. */\nexport interface StyleThemeScales {\n  fontSize: ThemeScaleOption[]\n  fontWeight: ThemeScaleOption[]\n  zIndex: ThemeScaleOption[]\n  /** The box styler's spacing ladder (AGL-2486, item 5). */\n  spacing: SpacingScaleOption[]\n  /** Corner-radius presets on the theme's shape scale (AGL-2486). */\n  cornerRadius: PresetChoiceOption[]\n  /** Drop-shadow presets named by what they look like (AGL-2486). */\n  shadow: PresetChoiceOption[]\n  /** The theme's own faces, then web-safe stacks (AGL-2486). */\n  fontFamily: PresetChoiceOption[]\n  /** Whole typography variants — `typography: 'h2'` (AGL-2486). */\n  typographyVariant: PresetChoiceOption[]\n  /** Grid/flex gaps on the theme's spacing ladder (AGL-2486). */\n  gap: PresetChoiceOption[]\n}\n\nexport function buildStyleThemeScales(\n  theme: ThemeScaleSource | undefined,\n): StyleThemeScales {\n  return {\n    fontSize: buildFontSizeScaleOptions(theme),\n    fontWeight: buildFontWeightScaleOptions(theme),\n    zIndex: buildZIndexScaleOptions(theme),\n    spacing: buildSpacingScaleOptions(theme),\n    cornerRadius: buildCornerRadiusChoices(theme),\n    shadow: buildShadowChoices(theme),\n    fontFamily: buildFontFamilyChoices(theme),\n    typographyVariant: buildTypographyVariantChoices(theme),\n    gap: buildGapChoices(theme),\n  }\n}\n\n/* ── Corner radius ────────────────────────────────────────────────────── */\n\n/**\n * MUI's own unit for a bare `borderRadius` number, and its default.\n *\n * `borderRadius: 2` renders 8px because MUI multiplies the number by\n * `shape.borderRadius` (4 unless a host changed it) — the same\n * theme-following arithmetic `spacing` gets, and the reason the presets\n * below store NUMBERS. A host that set `shape.borderRadius: 6` gets a\n * ladder of its own without anyone editing this file.\n */\nconst DEFAULT_SHAPE_RADIUS = 4\n\nfunction shapeRadiusUnit(theme: ThemeScaleSource | undefined): number {\n  const raw = theme?.shape?.borderRadius\n  if (typeof raw === 'number' && Number.isFinite(raw)) return raw\n  // A theme may carry a CSS length (`'4px'`); read the leading number so\n  // the hints stay right rather than silently reverting to the default.\n  if (typeof raw === 'string') {\n    const parsed = Number.parseFloat(raw)\n    if (Number.isFinite(parsed)) return parsed\n  }\n  return DEFAULT_SHAPE_RADIUS\n}\n\n/**\n * The rounding ladder, named the way an author describes a shape rather\n * than the way CSS spells one (AGL-2486).\n *\n * A text box for corner radius invites three value systems at once — a pixel\n * length, a percentage, or a theme multiple — and two of them are wrong,\n * because the theme scale behind this property is SHAPE, not spacing. Every\n * rung here is a theme multiple except the two that cannot be: a pill needs a\n * radius larger than the box can ever be, and a circle is a percentage.\n */\nconst RADIUS_STEPS: ReadonlyArray<{ step: number; label: string }> = [\n  { step: 0, label: 'Square' },\n  { step: 1, label: 'Slightly rounded' },\n  { step: 2, label: 'Rounded' },\n  { step: 3, label: 'More rounded' },\n  { step: 4, label: 'Very rounded' },\n]\n\n/**\n * A radius large enough that any box reads as a pill (CSS clamps a radius\n * to half the shorter side), expressed in px rather than as a theme\n * multiple because it is deliberately NOT following the theme — a pill is\n * a shape, not a spacing decision.\n */\nconst PILL_RADIUS = '9999px'\n\n/** Corner-radius presets, with what each resolves to in THIS theme. */\nexport function buildCornerRadiusChoices(\n  theme: ThemeScaleSource | undefined,\n): PresetChoiceOption[] {\n  const unit = shapeRadiusUnit(theme)\n  const options: PresetChoiceOption[] = RADIUS_STEPS.map(({ step, label }) => ({\n    value: step,\n    label,\n    hint: `${step * unit}px`,\n    // The menu tile draws the real shape, so the choice is made by looking.\n    preview: `${step * unit}px`,\n  }))\n  options.push({ value: PILL_RADIUS, label: 'Pill', preview: PILL_RADIUS })\n  options.push({\n    value: '50%',\n    label: 'Circle',\n    hint: 'square elements only',\n    preview: '50%',\n  })\n  return options\n}\n\n/* ── Shadow ───────────────────────────────────────────────────────────── */\n\n/**\n * Drop-shadow presets named by what they LOOK like (AGL-2486).\n *\n * The labels say what the shadow looks like, `No shadow` is offered as the\n * real value it is (a component or the theme may be drawing one), and the\n * escape hatch is a `Custom…` entry in this very control rather than a helper\n * pointing at the custom-CSS section.\n *\n * ## The menu is SHORT but the values are theme ELEVATIONS\n *\n * Two constraints pull apart here. MUI's ladder is 25 near-identical Material\n * elevations, which is a worse menu than a handful of shadows that visibly\n * differ — nobody should scroll 25 rows. But a literal CSS shadow is a bespoke\n * value that ignores `theme.shadows`, so a host that retunes its elevations\n * leaves every stored shadow behind.\n *\n * Both hold at once by curating INDICES: six rungs off the host's own\n * ladder, each stored as the number `boxShadow` already resolves through\n * (`themeKey: 'shadows'`), and each previewing the CSS that number renders\n * so the row still shows what it looks like. Same trick as Corner Radius —\n * store the theme multiple, preview the resolved value.\n *\n * `none` stays a string because it is the real value it is: a component or\n * the theme may be drawing a shadow this element wants gone.\n */\nconst SHADOW_STEPS: ReadonlyArray<{ elevation: number; label: string }> = [\n  { elevation: 1, label: 'Barely there — a hairline lift' },\n  { elevation: 3, label: 'Soft — sits on the page' },\n  { elevation: 6, label: 'Lifted — floats a little' },\n  { elevation: 12, label: 'Raised — floats well above' },\n  { elevation: 24, label: 'Highest — dialog level' },\n]\n\n/**\n * Literal CSS shadows, reached only when a theme carries no usable `shadows`\n * array, so the control never degrades to an empty menu on a host with an\n * unusual theme.\n */\nconst FALLBACK_SHADOWS: ReadonlyArray<{ value: string; label: string }> = [\n  { value: '0 1px 3px rgba(0,0,0,0.2)', label: 'Soft — sits on the page' },\n  { value: '0 4px 12px rgba(0,0,0,0.15)', label: 'Lifted — floats a little' },\n  { value: '0 12px 32px rgba(0,0,0,0.25)', label: 'Raised — floats well above' },\n  {\n    value: 'inset 0 2px 6px rgba(0,0,0,0.2)',\n    label: 'Inset — pressed into the page',\n  },\n]\n\nexport function buildShadowChoices(\n  theme?: ThemeScaleSource | undefined,\n): PresetChoiceOption[] {\n  const shadows = theme?.shadows\n  const options: PresetChoiceOption[] = [{ value: 'none', label: 'No shadow' }]\n  if (!Array.isArray(shadows) || shadows.length === 0) {\n    for (const entry of FALLBACK_SHADOWS) {\n      options.push({ value: entry.value, label: entry.label, preview: entry.value })\n    }\n    return options\n  }\n  for (const { elevation, label } of SHADOW_STEPS) {\n    const resolved = shadows[elevation]\n    // A host with a shorter ladder simply offers fewer rungs rather than\n    // storing an index that resolves to nothing.\n    if (typeof resolved !== 'string' || !resolved || resolved === 'none') continue\n    options.push({\n      value: elevation,\n      label,\n      hint: `Elevation ${elevation}`,\n      preview: resolved,\n    })\n  }\n  return options\n}\n\n/* ── Font family ──────────────────────────────────────────────────────── */\n\n/**\n * The typography variants whose own `fontFamily` is worth offering. A theme\n * that gives headings a display face and body a text face has TWO answers\n * an author should be able to pick, and neither of them is a font name they\n * have to know how to spell.\n */\nconst FONT_FAMILY_VARIANTS: ReadonlyArray<{ key: string; label: string }> = [\n  { key: 'h1', label: 'Theme heading font' },\n  { key: 'body1', label: 'Theme body font' },\n  { key: 'button', label: 'Theme button font' },\n]\n\n/**\n * Web-safe stacks, offered AFTER the theme's own faces.\n *\n * Deliberately short and generic: these are the families that render\n * without a webfont on every platform, so picking one can never cost a\n * page-load or leave a visitor on a fallback the author never saw. Anything\n * else — a Google font, a licensed face — is a Custom… value, which is the\n * honest place for it because it also needs the font to be loaded.\n */\nconst WEB_SAFE_FONTS: ReadonlyArray<{ value: string; label: string }> = [\n  { value: 'system-ui, sans-serif', label: 'System sans-serif' },\n  { value: 'Georgia, serif', label: 'Georgia (serif)' },\n  { value: '\"Times New Roman\", Times, serif', label: 'Times (serif)' },\n  { value: 'Arial, Helvetica, sans-serif', label: 'Arial (sans-serif)' },\n  { value: 'Verdana, Geneva, sans-serif', label: 'Verdana (sans-serif)' },\n  {\n    value: '\"Trebuchet MS\", Helvetica, sans-serif',\n    label: 'Trebuchet (sans-serif)',\n  },\n  { value: '\"Courier New\", Courier, monospace', label: 'Courier (monospace)' },\n]\n\n/** The first word of a stack, for a hint that fits a narrow menu row. */\nfunction firstFamily(stack: string): string {\n  const first = stack.split(',')[0] ?? ''\n  return first.trim().replace(/^[\"']|[\"']$/g, '')\n}\n\n/**\n * Font-family choices: the SITE THEME's own faces first, then web-safe\n *\n * The old field was free text carrying the advice *\"Prefer theme typography\n * when possible\"* — advice with no way to act on it. Leading with the\n * theme's faces makes the recommended answer the first one in reach, and\n * every row renders its own label in its own face so the choice can be made\n * by looking.\n *\n * A theme face is stored as the resolved STACK rather than as a token path,\n * because MUI declares `fontFamily` with `themeKey: 'typography'` and\n * `typography.fontFamily` is the only path that resolves — `h1.fontFamily`\n * does not. Duplicates are collapsed so a theme using one face everywhere\n * offers it once.\n */\nexport function buildFontFamilyChoices(\n  theme: ThemeScaleSource | undefined,\n): PresetChoiceOption[] {\n  const typography = theme?.typography\n  const options: PresetChoiceOption[] = []\n  const seen = new Set<string>()\n  const push = (value: string, label: string) => {\n    const stack = value.trim()\n    if (stack === '' || seen.has(stack)) return\n    seen.add(stack)\n    options.push({ value: stack, label, hint: firstFamily(stack) })\n  }\n  if (typography) {\n    const base = typography['fontFamily']\n    if (typeof base === 'string') push(base, 'Theme default font')\n    for (const { key, label } of FONT_FAMILY_VARIANTS) {\n      const variant = typography[key]\n      if (!variant || typeof variant !== 'object') continue\n      const family = (variant as Record<string, unknown>)['fontFamily']\n      if (typeof family === 'string') push(family, label)\n    }\n  }\n  for (const font of WEB_SAFE_FONTS) push(font.value, font.label)\n  return options\n}\n\n/* ── Typography variant ───────────────────────────────────────────────── */\n\n/**\n * Whole text styles from `theme.typography` (AGL-2486).\n *\n * Every other control in this group sets ONE property, so matching a heading\n * to the theme takes five correct picks in a row — face, size, weight, line\n * height, letter spacing — and getting any of them wrong leaves text that\n * looks almost right. `typography: 'h2'` is a single sx key that applies all\n * of them at once, and it is the key MUI itself reaches for.\n *\n * Without this control a page can carry eleven headings at MUI's default `h2`\n * — Light 300 at 60px — while every panel in the besigner reports nothing\n * wrong: no field says \"this is a Heading 2\", only fields that say \"this is\n * 60px\" once somebody types it.\n *\n * The hint names what the variant resolves to in THIS theme rather than in\n * the abstract, because \"Heading 2\" means nothing until you know the host\n * made it 40px semibold.\n */\nexport function buildTypographyVariantChoices(\n  theme: ThemeScaleSource | undefined,\n): PresetChoiceOption[] {\n  const typography = theme?.typography\n  if (!typography) return []\n  const options: PresetChoiceOption[] = []\n  for (const { key, label } of themeTypographyVariants(typography)) {\n    const variant = typography[key]\n    if (!variant || typeof variant !== 'object') continue\n    const { fontSize, fontWeight } = variant as Record<string, unknown>\n    const parts = [hintOf(fontSize), hintOf(fontWeight) && `weight ${hintOf(fontWeight)}`]\n      .filter(Boolean)\n      .join(' · ')\n    options.push({ value: key, label, hint: parts || undefined })\n  }\n  return options\n}\n\n/* ── Gap ──────────────────────────────────────────────────────────────── */\n\n/**\n * Grid and flex gaps on the theme's spacing ladder (AGL-2486).\n *\n * A free-text box for `gap`, `rowGap` or `columnGap` reads as a CSS length\n * question and gets answered with one — but MUI runs all three through\n * `createUnaryUnit(theme, 'spacing', …)`, exactly like margin and padding. So\n * `gap: 2` is a theme multiple that follows a host retuning its unit, and\n * `gap: '16px'` is a bespoke value that does not.\n *\n * These are the same rungs and the same labels the box styler offers for\n * margin and padding, so the two controls agree; gaps only sit apart because\n * they live in the Grid and Flex groups.\n *\n * A `PresetChoiceOption` rather than a `ThemeScaleOption` because the value\n * STORED is a number and that interface is string-only — the same reason\n * Corner Radius is a preset.\n */\nexport function buildGapChoices(\n  theme: ThemeScaleSource | undefined,\n): PresetChoiceOption[] {\n  const spacing = theme?.spacing\n  const options: PresetChoiceOption[] = []\n  for (const { step, label } of SPACING_STEPS) {\n    const hint = resolveSpacing(spacing, step)\n    if (hint === '') continue\n    options.push({ value: step, label, hint })\n  }\n  return options\n}\n"],"names":["humanizeKey","key","spaced","replace","trim","toLowerCase","charAt","toUpperCase","slice","hintOf","value","Number","isFinite","FONT_SIZE_VARIANTS","label","themeTypographyVariants","typography","known","Set","map","entry","extra","Object","keys","has","size","fontSize","parsed","parseFloat","String","push","sort","a","b","buildFontSizeScaleOptions","theme","options","variant","hint","FONT_WEIGHT_KEY","themeFontWeightTokens","found","match","exec","raw","weight","FONT_WEIGHT_LADDER","buildFontWeightScaleOptions","undefined","buildZIndexScaleOptions","zIndex","filter","SPACING_STEPS","step","resolveSpacing","spacing","resolved","buildSpacingScaleOptions","buildStyleThemeScales","fontWeight","cornerRadius","buildCornerRadiusChoices","shadow","buildShadowChoices","fontFamily","buildFontFamilyChoices","typographyVariant","buildTypographyVariantChoices","gap","buildGapChoices","DEFAULT_SHAPE_RADIUS","shapeRadiusUnit","shape","borderRadius","RADIUS_STEPS","PILL_RADIUS","unit","preview","SHADOW_STEPS","elevation","FALLBACK_SHADOWS","shadows","Array","isArray","length","FONT_FAMILY_VARIANTS","WEB_SAFE_FONTS","firstFamily","stack","first","split","seen","add","base","family","font","parts","Boolean","join"],"mappings":"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"}

package/src/lib/utils/token-editable-dom.d.ts

@@ -0,0 +1,82 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { type ResolvedTokenLabel, type TokenSegment } from './token-segments';
+/**
+ * DOM side of the token-pill editors (AGL-586): mapping between a
+ * contentEditable surface holding text nodes + atomic pill elements and
+ * the segment/unit model in `token-segments.ts`.
+ *
+ * Pills are `<span data-token="{{...}}" contenteditable="false">` elements
+ * whose TEXT is the friendly label — never serialized. Reading the DOM
+ * back emits the raw token from the `data-token` attribute, so the stored
+ * string always keeps the id-based grammar.
+ *
+ * Offset mapping mirrors the AGL-582 markdown editor's TreeWalker
+ * approach, with one twist: offsets are counted in UNITS (text char = 1,
+ * pill = 1 regardless of its label length) so a caret can never address
+ * the inside of a pill.
+ */
+/** Attribute carrying the raw token on a pill element. */
+export declare const TOKEN_PILL_ATTR = "data-token";
+/** Attribute carrying the pill's color family (see token-pill styles). */
+export declare const TOKEN_PILL_GROUP_ATTR = "data-token-group";
+/**
+ * Creates a pill element for direct-DOM surfaces (the inline canvas text
+ * editor). React surfaces render the same attributes via `TokenPill`; the
+ * container-level styles key off the data attributes, so both kinds of
+ * pill look identical.
+ */
+export declare function createTokenPillElement(doc: Document, token: string, resolved: ResolvedTokenLabel): HTMLSpanElement;
+/**
+ * Reads an editable surface back into segments: text nodes emit text, pill
+ * elements emit their raw `data-token`, `<br>` emits a newline, and block
+ * wrappers the browser may sneak in (paste, IME) emit a leading newline.
+ * The pill LABEL text never leaks into the serialized value.
+ */
+export declare function readTokenSegmentsFromDom(root: HTMLElement): TokenSegment[];
+/**
+ * Unit offset of a DOM point within `root`. Points inside a pill clamp to
+ * the pill's start (a caret can't live inside an atomic token).
+ */
+export declare function unitOffsetFromDomPoint(root: HTMLElement, node: Node, offset: number): number;
+/**
+ * DOM point for a unit offset. Landing on a pill boundary returns the
+ * position in the pill's PARENT (before/after the pill element) so the
+ * caret sits beside the atomic token, never inside it.
+ */
+export declare function domPointFromUnitOffset(root: HTMLElement, target: number): {
+    node: Node;
+    offset: number;
+};
+/** Current selection as unit offsets, or null when outside `root`. */
+export declare function selectionUnitsWithin(root: HTMLElement): {
+    start: number;
+    end: number;
+} | null;
+/** Places the selection at the given unit offsets inside `root`. */
+export declare function setSelectionUnits(root: HTMLElement, start: number, end: number): void;
+/**
+ * Replaces raw `{{...}}` occurrences in text nodes under `root` with pill
+ * elements (inline-editor open path). Returns how many pills were made.
+ */
+export declare function materializeTokenPillsInElement(root: HTMLElement, resolve: (token: string) => ResolvedTokenLabel): number;
+/**
+ * Replaces every pill under `root` with a text node holding its raw token
+ * (inline-editor commit path — run on a CLONE before sanitizing, so the
+ * stored string carries `{{var:id}}` grammar, never pill labels).
+ */
+export declare function replacePillsWithTokenText(root: HTMLElement): void;

package/src/lib/utils/token-editable-dom.js

@@ -0,0 +1,280 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ import { TOKEN_SEGMENT_PATTERN } from "./token-segments.js";
+/**
+ * DOM side of the token-pill editors (AGL-586): mapping between a
+ * contentEditable surface holding text nodes + atomic pill elements and
+ * the segment/unit model in `token-segments.ts`.
+ *
+ * Pills are `<span data-token="{{...}}" contenteditable="false">` elements
+ * whose TEXT is the friendly label — never serialized. Reading the DOM
+ * back emits the raw token from the `data-token` attribute, so the stored
+ * string always keeps the id-based grammar.
+ *
+ * Offset mapping mirrors the AGL-582 markdown editor's TreeWalker
+ * approach, with one twist: offsets are counted in UNITS (text char = 1,
+ * pill = 1 regardless of its label length) so a caret can never address
+ * the inside of a pill.
+ */ /** Attribute carrying the raw token on a pill element. */ export const TOKEN_PILL_ATTR = 'data-token';
+/** Attribute carrying the pill's color family (see token-pill styles). */ export const TOKEN_PILL_GROUP_ATTR = 'data-token-group';
+// Deliberately NOT a type predicate: a `node is HTMLElement` guard would
+// narrow an already-HTMLElement argument to `never` in the else branch.
+const isPillElement = (node)=>node.nodeType === Node.ELEMENT_NODE && node.hasAttribute(TOKEN_PILL_ATTR);
+/**
+ * Creates a pill element for direct-DOM surfaces (the inline canvas text
+ * editor). React surfaces render the same attributes via `TokenPill`; the
+ * container-level styles key off the data attributes, so both kinds of
+ * pill look identical.
+ */ export function createTokenPillElement(doc, token, resolved) {
+    const pill = doc.createElement('span');
+    pill.setAttribute(TOKEN_PILL_ATTR, token);
+    pill.setAttribute(TOKEN_PILL_GROUP_ATTR, resolved.known ? resolved.group : 'unknown');
+    pill.setAttribute('contenteditable', 'false');
+    pill.setAttribute('role', 'button');
+    // The raw token stays inspectable as the tooltip (ids stored, names shown).
+    pill.setAttribute('title', token);
+    pill.textContent = resolved.label;
+    return pill;
+}
+const isBlockElement = (node)=>node.nodeType === Node.ELEMENT_NODE && /^(DIV|P|LI|UL|OL|H[1-6])$/.test(node.tagName);
+/**
+ * Reads an editable surface back into segments: text nodes emit text, pill
+ * elements emit their raw `data-token`, `<br>` emits a newline, and block
+ * wrappers the browser may sneak in (paste, IME) emit a leading newline.
+ * The pill LABEL text never leaks into the serialized value.
+ */ export function readTokenSegmentsFromDom(root) {
+    const segments = [];
+    const pushText = (text)=>{
+        if (!text) return;
+        const last = segments[segments.length - 1];
+        if ((last == null ? void 0 : last.type) === 'text') last.value += text;
+        else segments.push({
+            type: 'text',
+            value: text
+        });
+    };
+    const visit = (node)=>{
+        if (node.nodeType === Node.TEXT_NODE) {
+            var _node_textContent;
+            pushText((_node_textContent = node.textContent) != null ? _node_textContent : '');
+            return;
+        }
+        if (node.nodeType !== Node.ELEMENT_NODE) return;
+        const element = node;
+        if (isPillElement(element)) {
+            var _element_getAttribute;
+            const token = (_element_getAttribute = element.getAttribute(TOKEN_PILL_ATTR)) != null ? _element_getAttribute : '';
+            if (token) segments.push({
+                type: 'token',
+                value: token,
+                token
+            });
+            return;
+        }
+        if (element.tagName === 'BR') {
+            pushText('\n');
+            return;
+        }
+        if (isBlockElement(element) && segments.length > 0) pushText('\n');
+        element.childNodes.forEach(visit);
+    };
+    root.childNodes.forEach(visit);
+    return segments;
+}
+/** Unit length of a node subtree (text chars; pills and `<br>`s count 1). */ function unitLengthOfNode(node) {
+    if (node.nodeType === Node.TEXT_NODE) {
+        var _node_textContent;
+        return ((_node_textContent = node.textContent) != null ? _node_textContent : '').length;
+    }
+    if (node.nodeType !== Node.ELEMENT_NODE) return 0;
+    if (isPillElement(node)) return 1;
+    if (node.tagName === 'BR') return 1;
+    let length = 0;
+    node.childNodes.forEach((child)=>{
+        length += unitLengthOfNode(child);
+    });
+    return length;
+}
+/**
+ * Unit offset of a DOM point within `root`. Points inside a pill clamp to
+ * the pill's start (a caret can't live inside an atomic token).
+ */ export function unitOffsetFromDomPoint(root, node, offset) {
+    let units = 0;
+    const visit = (current)=>{
+        if (current === node) {
+            if (current.nodeType === Node.TEXT_NODE) {
+                var _current_textContent;
+                units += Math.min(offset, ((_current_textContent = current.textContent) != null ? _current_textContent : '').length);
+            } else if (!isPillElement(current)) {
+                const children = current.childNodes;
+                for(let index = 0; index < offset && index < children.length; index++){
+                    units += unitLengthOfNode(children[index]);
+                }
+            }
+            return true;
+        }
+        if (current.nodeType === Node.TEXT_NODE) {
+            var _current_textContent1;
+            units += ((_current_textContent1 = current.textContent) != null ? _current_textContent1 : '').length;
+            return false;
+        }
+        if (current.nodeType !== Node.ELEMENT_NODE) return false;
+        if (isPillElement(current)) {
+            // A point INSIDE the pill clamps to the pill start.
+            if (current.contains(node)) return true;
+            units += 1;
+            return false;
+        }
+        if (current.tagName === 'BR') {
+            units += 1;
+            return false;
+        }
+        for (const child of Array.from(current.childNodes)){
+            if (visit(child)) return true;
+        }
+        return false;
+    };
+    visit(root);
+    return units;
+}
+/**
+ * DOM point for a unit offset. Landing on a pill boundary returns the
+ * position in the pill's PARENT (before/after the pill element) so the
+ * caret sits beside the atomic token, never inside it.
+ */ export function domPointFromUnitOffset(root, target) {
+    var _visit;
+    let remaining = Math.max(0, target);
+    const visit = (parent)=>{
+        const children = parent.childNodes;
+        for(let index = 0; index < children.length; index++){
+            const child = children[index];
+            if (child.nodeType === Node.TEXT_NODE) {
+                var _child_textContent;
+                const length = ((_child_textContent = child.textContent) != null ? _child_textContent : '').length;
+                if (remaining <= length) return {
+                    node: child,
+                    offset: remaining
+                };
+                remaining -= length;
+                continue;
+            }
+            if (child.nodeType !== Node.ELEMENT_NODE) continue;
+            if (isPillElement(child) || child.tagName === 'BR') {
+                if (remaining === 0) return {
+                    node: parent,
+                    offset: index
+                };
+                remaining -= 1;
+                if (remaining === 0) return {
+                    node: parent,
+                    offset: index + 1
+                };
+                continue;
+            }
+            const found = visit(child);
+            if (found) return found;
+        }
+        return null;
+    };
+    return (_visit = visit(root)) != null ? _visit : {
+        node: root,
+        offset: root.childNodes.length
+    };
+}
+/** Current selection as unit offsets, or null when outside `root`. */ export function selectionUnitsWithin(root) {
+    var _root_ownerDocument_defaultView_getSelection, _root_ownerDocument_defaultView;
+    const selection = (_root_ownerDocument_defaultView = root.ownerDocument.defaultView) == null ? void 0 : (_root_ownerDocument_defaultView_getSelection = _root_ownerDocument_defaultView.getSelection) == null ? void 0 : _root_ownerDocument_defaultView_getSelection.call(_root_ownerDocument_defaultView);
+    if (!selection || selection.rangeCount === 0) return null;
+    const range = selection.getRangeAt(0);
+    if (!root.contains(range.startContainer) || !root.contains(range.endContainer)) {
+        return null;
+    }
+    const start = unitOffsetFromDomPoint(root, range.startContainer, range.startOffset);
+    const end = unitOffsetFromDomPoint(root, range.endContainer, range.endOffset);
+    return start <= end ? {
+        start,
+        end
+    } : {
+        start: end,
+        end: start
+    };
+}
+/** Places the selection at the given unit offsets inside `root`. */ export function setSelectionUnits(root, start, end) {
+    var _root_ownerDocument_defaultView_getSelection, _root_ownerDocument_defaultView;
+    const selection = (_root_ownerDocument_defaultView = root.ownerDocument.defaultView) == null ? void 0 : (_root_ownerDocument_defaultView_getSelection = _root_ownerDocument_defaultView.getSelection) == null ? void 0 : _root_ownerDocument_defaultView_getSelection.call(_root_ownerDocument_defaultView);
+    if (!selection) return;
+    const from = domPointFromUnitOffset(root, start);
+    const to = end === start ? from : domPointFromUnitOffset(root, end);
+    const range = root.ownerDocument.createRange();
+    range.setStart(from.node, from.offset);
+    range.setEnd(to.node, to.offset);
+    selection.removeAllRanges();
+    selection.addRange(range);
+}
+/**
+ * Replaces raw `{{...}}` occurrences in text nodes under `root` with pill
+ * elements (inline-editor open path). Returns how many pills were made.
+ */ export function materializeTokenPillsInElement(root, resolve) {
+    const doc = root.ownerDocument;
+    const walker = doc.createTreeWalker(root, NodeFilter.SHOW_TEXT, {
+        acceptNode: (node)=>{
+            var _node_parentElement;
+            return ((_node_parentElement = node.parentElement) == null ? void 0 : _node_parentElement.closest(`[${TOKEN_PILL_ATTR}]`)) ? NodeFilter.FILTER_REJECT : NodeFilter.FILTER_ACCEPT;
+        }
+    });
+    const targets = [];
+    for(let node = walker.nextNode(); node; node = walker.nextNode()){
+        var _node_textContent;
+        if (new RegExp(TOKEN_SEGMENT_PATTERN.source).test((_node_textContent = node.textContent) != null ? _node_textContent : '')) {
+            targets.push(node);
+        }
+    }
+    let count = 0;
+    for (const textNode of targets){
+        var _textNode_textContent;
+        const text = (_textNode_textContent = textNode.textContent) != null ? _textNode_textContent : '';
+        const fragment = doc.createDocumentFragment();
+        let cursor = 0;
+        const pattern = new RegExp(TOKEN_SEGMENT_PATTERN.source, 'g');
+        for(let match = pattern.exec(text); match; match = pattern.exec(text)){
+            if (match.index > cursor) {
+                fragment.appendChild(doc.createTextNode(text.slice(cursor, match.index)));
+            }
+            fragment.appendChild(createTokenPillElement(doc, match[0], resolve(match[0])));
+            count += 1;
+            cursor = match.index + match[0].length;
+        }
+        if (cursor < text.length) {
+            fragment.appendChild(doc.createTextNode(text.slice(cursor)));
+        }
+        textNode.replaceWith(fragment);
+    }
+    return count;
+}
+/**
+ * Replaces every pill under `root` with a text node holding its raw token
+ * (inline-editor commit path — run on a CLONE before sanitizing, so the
+ * stored string carries `{{var:id}}` grammar, never pill labels).
+ */ export function replacePillsWithTokenText(root) {
+    const pills = Array.from(root.querySelectorAll(`[${TOKEN_PILL_ATTR}]`));
+    for (const pill of pills){
+        var _pill_getAttribute;
+        const token = (_pill_getAttribute = pill.getAttribute(TOKEN_PILL_ATTR)) != null ? _pill_getAttribute : '';
+        pill.replaceWith(root.ownerDocument.createTextNode(token));
+    }
+}
+
+//# sourceMappingURL=token-editable-dom.js.map

package/src/lib/utils/token-editable-dom.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../../libs/besigner/feature/designer/src/lib/utils/token-editable-dom.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport {\n  type ResolvedTokenLabel,\n  type TokenSegment,\n  TOKEN_SEGMENT_PATTERN,\n} from './token-segments'\n\n/**\n * DOM side of the token-pill editors (AGL-586): mapping between a\n * contentEditable surface holding text nodes + atomic pill elements and\n * the segment/unit model in `token-segments.ts`.\n *\n * Pills are `<span data-token=\"{{...}}\" contenteditable=\"false\">` elements\n * whose TEXT is the friendly label — never serialized. Reading the DOM\n * back emits the raw token from the `data-token` attribute, so the stored\n * string always keeps the id-based grammar.\n *\n * Offset mapping mirrors the AGL-582 markdown editor's TreeWalker\n * approach, with one twist: offsets are counted in UNITS (text char = 1,\n * pill = 1 regardless of its label length) so a caret can never address\n * the inside of a pill.\n */\n\n/** Attribute carrying the raw token on a pill element. */\nexport const TOKEN_PILL_ATTR = 'data-token'\n\n/** Attribute carrying the pill's color family (see token-pill styles). */\nexport const TOKEN_PILL_GROUP_ATTR = 'data-token-group'\n\n// Deliberately NOT a type predicate: a `node is HTMLElement` guard would\n// narrow an already-HTMLElement argument to `never` in the else branch.\nconst isPillElement = (node: Node): boolean =>\n  node.nodeType === Node.ELEMENT_NODE &&\n  (node as HTMLElement).hasAttribute(TOKEN_PILL_ATTR)\n\n/**\n * Creates a pill element for direct-DOM surfaces (the inline canvas text\n * editor). React surfaces render the same attributes via `TokenPill`; the\n * container-level styles key off the data attributes, so both kinds of\n * pill look identical.\n */\nexport function createTokenPillElement(\n  doc: Document,\n  token: string,\n  resolved: ResolvedTokenLabel,\n): HTMLSpanElement {\n  const pill = doc.createElement('span')\n  pill.setAttribute(TOKEN_PILL_ATTR, token)\n  pill.setAttribute(\n    TOKEN_PILL_GROUP_ATTR,\n    resolved.known ? resolved.group : 'unknown',\n  )\n  pill.setAttribute('contenteditable', 'false')\n  pill.setAttribute('role', 'button')\n  // The raw token stays inspectable as the tooltip (ids stored, names shown).\n  pill.setAttribute('title', token)\n  pill.textContent = resolved.label\n  return pill\n}\n\nconst isBlockElement = (node: Node): boolean =>\n  node.nodeType === Node.ELEMENT_NODE &&\n  /^(DIV|P|LI|UL|OL|H[1-6])$/.test((node as HTMLElement).tagName)\n\n/**\n * Reads an editable surface back into segments: text nodes emit text, pill\n * elements emit their raw `data-token`, `<br>` emits a newline, and block\n * wrappers the browser may sneak in (paste, IME) emit a leading newline.\n * The pill LABEL text never leaks into the serialized value.\n */\nexport function readTokenSegmentsFromDom(root: HTMLElement): TokenSegment[] {\n  const segments: TokenSegment[] = []\n  const pushText = (text: string) => {\n    if (!text) return\n    const last = segments[segments.length - 1]\n    if (last?.type === 'text') last.value += text\n    else segments.push({ type: 'text', value: text })\n  }\n  const visit = (node: Node): void => {\n    if (node.nodeType === Node.TEXT_NODE) {\n      pushText(node.textContent ?? '')\n      return\n    }\n    if (node.nodeType !== Node.ELEMENT_NODE) return\n    const element = node as HTMLElement\n    if (isPillElement(element)) {\n      const token = element.getAttribute(TOKEN_PILL_ATTR) ?? ''\n      if (token) segments.push({ type: 'token', value: token, token })\n      return\n    }\n    if (element.tagName === 'BR') {\n      pushText('\\n')\n      return\n    }\n    if (isBlockElement(element) && segments.length > 0) pushText('\\n')\n    element.childNodes.forEach(visit)\n  }\n  root.childNodes.forEach(visit)\n  return segments\n}\n\n/** Unit length of a node subtree (text chars; pills and `<br>`s count 1). */\nfunction unitLengthOfNode(node: Node): number {\n  if (node.nodeType === Node.TEXT_NODE) {\n    return (node.textContent ?? '').length\n  }\n  if (node.nodeType !== Node.ELEMENT_NODE) return 0\n  if (isPillElement(node)) return 1\n  if ((node as HTMLElement).tagName === 'BR') return 1\n  let length = 0\n  node.childNodes.forEach((child) => {\n    length += unitLengthOfNode(child)\n  })\n  return length\n}\n\n/**\n * Unit offset of a DOM point within `root`. Points inside a pill clamp to\n * the pill's start (a caret can't live inside an atomic token).\n */\nexport function unitOffsetFromDomPoint(\n  root: HTMLElement,\n  node: Node,\n  offset: number,\n): number {\n  let units = 0\n  const visit = (current: Node): boolean => {\n    if (current === node) {\n      if (current.nodeType === Node.TEXT_NODE) {\n        units += Math.min(offset, (current.textContent ?? '').length)\n      } else if (!isPillElement(current)) {\n        const children = current.childNodes\n        for (let index = 0; index < offset && index < children.length; index++) {\n          units += unitLengthOfNode(children[index] as Node)\n        }\n      }\n      return true\n    }\n    if (current.nodeType === Node.TEXT_NODE) {\n      units += (current.textContent ?? '').length\n      return false\n    }\n    if (current.nodeType !== Node.ELEMENT_NODE) return false\n    if (isPillElement(current)) {\n      // A point INSIDE the pill clamps to the pill start.\n      if (current.contains(node)) return true\n      units += 1\n      return false\n    }\n    if ((current as HTMLElement).tagName === 'BR') {\n      units += 1\n      return false\n    }\n    for (const child of Array.from(current.childNodes)) {\n      if (visit(child)) return true\n    }\n    return false\n  }\n  visit(root)\n  return units\n}\n\n/**\n * DOM point for a unit offset. Landing on a pill boundary returns the\n * position in the pill's PARENT (before/after the pill element) so the\n * caret sits beside the atomic token, never inside it.\n */\nexport function domPointFromUnitOffset(\n  root: HTMLElement,\n  target: number,\n): { node: Node; offset: number } {\n  let remaining = Math.max(0, target)\n  const visit = (parent: Node): { node: Node; offset: number } | null => {\n    const children = parent.childNodes\n    for (let index = 0; index < children.length; index++) {\n      const child = children[index] as Node\n      if (child.nodeType === Node.TEXT_NODE) {\n        const length = (child.textContent ?? '').length\n        if (remaining <= length) return { node: child, offset: remaining }\n        remaining -= length\n        continue\n      }\n      if (child.nodeType !== Node.ELEMENT_NODE) continue\n      if (isPillElement(child) || (child as HTMLElement).tagName === 'BR') {\n        if (remaining === 0) return { node: parent, offset: index }\n        remaining -= 1\n        if (remaining === 0) return { node: parent, offset: index + 1 }\n        continue\n      }\n      const found = visit(child)\n      if (found) return found\n    }\n    return null\n  }\n  return visit(root) ?? { node: root, offset: root.childNodes.length }\n}\n\n/** Current selection as unit offsets, or null when outside `root`. */\nexport function selectionUnitsWithin(\n  root: HTMLElement,\n): { start: number; end: number } | null {\n  const selection = root.ownerDocument.defaultView?.getSelection?.()\n  if (!selection || selection.rangeCount === 0) return null\n  const range = selection.getRangeAt(0)\n  if (\n    !root.contains(range.startContainer) ||\n    !root.contains(range.endContainer)\n  ) {\n    return null\n  }\n  const start = unitOffsetFromDomPoint(\n    root,\n    range.startContainer,\n    range.startOffset,\n  )\n  const end = unitOffsetFromDomPoint(root, range.endContainer, range.endOffset)\n  return start <= end ? { start, end } : { start: end, end: start }\n}\n\n/** Places the selection at the given unit offsets inside `root`. */\nexport function setSelectionUnits(\n  root: HTMLElement,\n  start: number,\n  end: number,\n): void {\n  const selection = root.ownerDocument.defaultView?.getSelection?.()\n  if (!selection) return\n  const from = domPointFromUnitOffset(root, start)\n  const to = end === start ? from : domPointFromUnitOffset(root, end)\n  const range = root.ownerDocument.createRange()\n  range.setStart(from.node, from.offset)\n  range.setEnd(to.node, to.offset)\n  selection.removeAllRanges()\n  selection.addRange(range)\n}\n\n/**\n * Replaces raw `{{...}}` occurrences in text nodes under `root` with pill\n * elements (inline-editor open path). Returns how many pills were made.\n */\nexport function materializeTokenPillsInElement(\n  root: HTMLElement,\n  resolve: (token: string) => ResolvedTokenLabel,\n): number {\n  const doc = root.ownerDocument\n  const walker = doc.createTreeWalker(root, NodeFilter.SHOW_TEXT, {\n    acceptNode: (node) =>\n      node.parentElement?.closest(`[${TOKEN_PILL_ATTR}]`)\n        ? NodeFilter.FILTER_REJECT\n        : NodeFilter.FILTER_ACCEPT,\n  })\n  const targets: Text[] = []\n  for (let node = walker.nextNode(); node; node = walker.nextNode()) {\n    if (new RegExp(TOKEN_SEGMENT_PATTERN.source).test(node.textContent ?? '')) {\n      targets.push(node as Text)\n    }\n  }\n  let count = 0\n  for (const textNode of targets) {\n    const text = textNode.textContent ?? ''\n    const fragment = doc.createDocumentFragment()\n    let cursor = 0\n    const pattern = new RegExp(TOKEN_SEGMENT_PATTERN.source, 'g')\n    for (let match = pattern.exec(text); match; match = pattern.exec(text)) {\n      if (match.index > cursor) {\n        fragment.appendChild(\n          doc.createTextNode(text.slice(cursor, match.index)),\n        )\n      }\n      fragment.appendChild(\n        createTokenPillElement(doc, match[0], resolve(match[0])),\n      )\n      count += 1\n      cursor = match.index + match[0].length\n    }\n    if (cursor < text.length) {\n      fragment.appendChild(doc.createTextNode(text.slice(cursor)))\n    }\n    textNode.replaceWith(fragment)\n  }\n  return count\n}\n\n/**\n * Replaces every pill under `root` with a text node holding its raw token\n * (inline-editor commit path — run on a CLONE before sanitizing, so the\n * stored string carries `{{var:id}}` grammar, never pill labels).\n */\nexport function replacePillsWithTokenText(root: HTMLElement): void {\n  const pills = Array.from(root.querySelectorAll(`[${TOKEN_PILL_ATTR}]`))\n  for (const pill of pills) {\n    const token = pill.getAttribute(TOKEN_PILL_ATTR) ?? ''\n    pill.replaceWith(root.ownerDocument.createTextNode(token))\n  }\n}\n"],"names":["TOKEN_SEGMENT_PATTERN","TOKEN_PILL_ATTR","TOKEN_PILL_GROUP_ATTR","isPillElement","node","nodeType","Node","ELEMENT_NODE","hasAttribute","createTokenPillElement","doc","token","resolved","pill","createElement","setAttribute","known","group","textContent","label","isBlockElement","test","tagName","readTokenSegmentsFromDom","root","segments","pushText","text","last","length","type","value","push","visit","TEXT_NODE","element","getAttribute","childNodes","forEach","unitLengthOfNode","child","unitOffsetFromDomPoint","offset","units","current","Math","min","children","index","contains","Array","from","domPointFromUnitOffset","target","remaining","max","parent","found","selectionUnitsWithin","selection","ownerDocument","defaultView","getSelection","rangeCount","range","getRangeAt","startContainer","endContainer","start","startOffset","end","endOffset","setSelectionUnits","to","createRange","setStart","setEnd","removeAllRanges","addRange","materializeTokenPillsInElement","resolve","walker","createTreeWalker","NodeFilter","SHOW_TEXT","acceptNode","parentElement","closest","FILTER_REJECT","FILTER_ACCEPT","targets","nextNode","RegExp","source","count","textNode","fragment","createDocumentFragment","cursor","pattern","match","exec","appendChild","createTextNode","slice","replaceWith","replacePillsWithTokenText","pills","querySelectorAll"],"mappings":"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"}

package/src/lib/utils/token-segments.d.ts

@@ -0,0 +1,111 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import type { BindingOption } from '../contexts/binding-picker-context';
+/**
+ * Token-pill segment model (AGL-586). Stored prop strings keep the raw
+ * id-based `{{...}}` grammar (AGL-100/185) — these helpers only SPLIT a
+ * string into runs of plain text and atomic tokens so editors can render
+ * the tokens as friendly, clickable pills. Serializing the segments always
+ * reproduces the exact input string; nothing here ever rewrites a token.
+ *
+ * Offset model: editor carets address "units", where every plain-text
+ * character is 1 unit and every token — however long its raw text — is 1
+ * atomic unit. A caret can therefore sit before or after a pill but never
+ * inside one, which is exactly how the pills behave in the DOM
+ * (`contenteditable="false"`).
+ */
+export interface TokenSegment {
+    type: 'text' | 'token';
+    /** The literal slice of the serialized string (raw `{{...}}` for tokens). */
+    value: string;
+    /** Set on token segments: the raw token, identical to `value`. */
+    token?: string;
+}
+/**
+ * Any `{{...}}` occurrence without nested braces — var:/fn:/entry./
+ * collection./item.* AND unknown tokens alike. `{{a{{b}}` yields the text
+ * `{{a` plus the token `{{b}}` (the opener without a closer is plain text).
+ */
+export declare const TOKEN_SEGMENT_PATTERN: RegExp;
+/** Splits `text` on `{{...}}` occurrences into text/token segments. */
+export declare function parseTokenSegments(text: string): TokenSegment[];
+/** Joins segments back to the exact stored string (lossless round-trip). */
+export declare function serializeTokenSegments(segments: TokenSegment[]): string;
+/** True when any text run still holds a complete raw `{{...}}` token. */
+export declare function hasUnmaterializedTokens(segments: TokenSegment[]): boolean;
+/** Unit length of one segment: text = char count, token = 1 atomic unit. */
+export declare function segmentUnitLength(segment: TokenSegment): number;
+/** Total unit length of a segment list (pills count as 1 unit each). */
+export declare function segmentsUnitLength(segments: TokenSegment[]): number;
+/**
+ * Extracts [from, to) in unit offsets. Tokens are atomic: since a token is
+ * exactly 1 unit, an integer range either includes it wholly or not at all
+ * — a caret can never split a pill.
+ */
+export declare function sliceSegmentsByUnits(segments: TokenSegment[], from: number, to: number): TokenSegment[];
+/**
+ * Splices `replacement` into `segments` at the unit-offset selection,
+ * replacing any selected range — the caret-preserving insert used by the
+ * {x} picker (AGL-583 semantics, pill-aware). A null/undefined start means
+ * "no caret captured": the replacement appends at the end. Returns the new
+ * segment list and the caret unit just after the inserted content.
+ */
+export declare function spliceSegmentsAtUnits(segments: TokenSegment[], replacement: TokenSegment[], start?: number | null, end?: number | null): {
+    segments: TokenSegment[];
+    caretUnit: number;
+};
+/** A single token segment for `spliceSegmentsAtUnits` insertion. */
+export declare function tokenSegment(token: string): TokenSegment;
+/** A single text segment for `spliceSegmentsAtUnits` insertion. */
+export declare function textSegment(text: string): TokenSegment;
+/** Which catalog family a token belongs to — drives the pill color. */
+export type TokenGroup = 'variable' | 'function' | 'entry' | 'collection' | 'dataset' | 'property' | 'host' | 'unknown';
+/**
+ * Display-name inputs for {@link resolveTokenLabel}: the picker options
+ * (which already carry friendly labels for every insertable token), the
+ * host's variable/function docs keyed by id (AGL-194), and the ancestor
+ * repeatable's dataset model fields (id → current display name).
+ */
+export interface TokenLabelContext {
+    options?: BindingOption[];
+    variables?: Record<string, {
+        name?: string;
+    } | undefined>;
+    functions?: Record<string, {
+        name?: string;
+    } | undefined>;
+    datasetFields?: Array<{
+        id: string;
+        label: string;
+    }>;
+}
+export interface ResolvedTokenLabel {
+    /** Friendly display name (the CURRENT name — ids stay in storage). */
+    label: string;
+    /** Family for the pill color; shape-derived, stable across renames. */
+    group: TokenGroup;
+    /** False when the referent can't be resolved (warning-colored pill). */
+    known: boolean;
+}
+/**
+ * Resolves a raw token to its display name (AGL-586 requirement 2: users
+ * see NAMES, storage keeps IDS). The group comes from the token's shape so
+ * pills stay consistently colored even when the referent is missing;
+ * `known: false` marks unresolvable tokens for warning styling with the
+ * raw token surfaced as the tooltip.
+ */
+export declare function resolveTokenLabel(token: string, context?: TokenLabelContext): ResolvedTokenLabel;