@things-factory/shell 10.1.20 → 10.1.27

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@things-factory/shell",
-  "version": "10.1.20",
+  "version": "10.1.27",
   "description": "Core module for framework",
   "bin": {
     "things-factory": "bin/things-factory",
@@ -126,5 +126,5 @@
     "pg": "^8.7.3",
     "sqlite3": "^5.0.8"
   },
-  "gitHead": "6bd01660a4b28554bbe6ae4ee58f3ff844c5af69"
+  "gitHead": "d04dc762cacf2aac8ba0b0f5d768eca365fc09da"
 }

package/tests/control-height-tokens.test.ts

@@ -0,0 +1,113 @@
+/**
+ * Control heights: the shell theme declares the tokens, and @operato/styles declares the same names
+ * with the same defaults (ADR-0060 decision 6). The theme is the value of record; the components need
+ * a fallback because they cannot see the shell. Written in two places, so this test holds them
+ * together - change one and it fails until the other follows.
+ *
+ * Two bundles: button heights (ACTION_HEIGHT_TOKENS, ui-tokens.css) and input heights
+ * (FORM_ELEMENT_HEIGHT_TOKENS, spacing.css). Material buttons and filter chips are sized once in the
+ * theme from those tokens; Material text fields and selects keep their own size.
+ */
+
+import { existsSync, readFileSync } from 'fs'
+import path from 'path'
+
+const THEMES = path.resolve(__dirname, '../client/themes')
+
+function stylesConstants(file: string, name: string): Record<string, number> {
+  const root = path.dirname(require.resolve('@operato/styles/package.json'))
+  const built = path.join(root, 'dist/src', file)
+
+  if (!existsSync(built)) {
+    throw new Error(`the installed @operato/styles (${root}) has no ${file} - it predates ADR-0060 decision 6`)
+  }
+
+  const body = readFileSync(built, 'utf-8').match(new RegExp(`${name}\\s*=\\s*\\{([\\s\\S]*?)\\}`))
+  if (!body) throw new Error(`${name} was not found in @operato/styles ${file}`)
+
+  return Object.fromEntries([...body[1].matchAll(/'(--[a-z-]+)':\s*(\d+)/g)].map(m => [m[1], Number(m[2])]))
+}
+
+function themeDeclarations(file: string): Record<string, string> {
+  const css = readFileSync(path.join(THEMES, file), 'utf-8').replace(/\/\*[\s\S]*?\*\//g, '')
+  return Object.fromEntries([...css.matchAll(/(--[a-z0-9-]+)\s*:\s*([^;]+);/g)].map(m => [m[1], m[2].trim()]))
+}
+
+function expectPlatformSlots(constants: Record<string, number>, theme: Record<string, string>) {
+  /*
+   * Each token opens a slot for operato-suite and falls back to the platform default
+   * (ADR-0060 decision 6-1). The suite never redefines the token itself, so nothing depends on which
+   * stylesheet loads last.
+   */
+  for (const [token, px] of Object.entries(constants)) {
+    expect({ token, value: theme[token] }).toEqual({ token, value: `var(--suite-${token.slice(2)}, ${px}px)` })
+  }
+}
+
+describe('button height tokens', () => {
+  it('the shell theme opens every @operato/styles action height as a suite slot over the platform default', () => {
+    const constants = stylesConstants('action-heights.js', 'ACTION_HEIGHT_TOKENS')
+
+    expect(Object.keys(constants).sort()).toEqual([
+      '--cell-action-height',
+      '--context-action-height',
+      '--form-action-height',
+      '--popup-action-height'
+    ])
+    expectPlatformSlots(constants, themeDeclarations('ui-tokens.css'))
+  })
+
+  it('Material buttons take the form height, set once in the theme', () => {
+    const theme = themeDeclarations('material-theme.css')
+
+    for (const kind of ['filled', 'outlined', 'text', 'elevated', 'filled-tonal']) {
+      expect({ kind, value: theme[`--md-${kind}-button-container-height`] }).toEqual({
+        kind,
+        value: 'var(--form-action-height)'
+      })
+    }
+  })
+
+  it('assist chips: 36px (44px by finger) on the platform, the page action height in the operato products', () => {
+    const css = readFileSync(path.join(THEMES, 'layout-theme.css'), 'utf-8').replace(/\/\*[\s\S]*?\*\//g, '')
+    const values = [...css.matchAll(/--md-assist-chip-container-height\s*:\s*([^;]+);/g)].map(m => m[1].trim())
+
+    expect(values).toEqual([
+      'var(--suite-context-action-height, 36px)',
+      'var(--suite-context-action-height, var(--ui-tap, 44px))'
+    ])
+  })
+})
+
+describe('input height tokens', () => {
+  it('the shell theme opens small, medium and large as suite slots over the platform defaults, and nothing else', () => {
+    const constants = stylesConstants('form-element-heights.js', 'FORM_ELEMENT_HEIGHT_TOKENS')
+    const theme = themeDeclarations('spacing.css')
+
+    expect(Object.keys(constants).sort()).toEqual([
+      '--form-element-height-large',
+      '--form-element-height-medium',
+      '--form-element-height-small'
+    ])
+    expectPlatformSlots(constants, theme)
+    expect(
+      Object.keys(theme)
+        .filter(name => name.startsWith('--form-element-height-'))
+        .sort()
+    ).toEqual(Object.keys(constants).sort())
+  })
+
+  it('Material text fields, selects and filter chips keep their own size', () => {
+    /* Their label floats above the value inside the box and needs the room (user decision). */
+    const theme = themeDeclarations('material-theme.css')
+    const fieldSizes = Object.keys(theme).filter(name =>
+      /^--md-(outlined|filled)-(text-field|select-text-field|field|select)-.*(space|height|text-size|line-height|populated-size)$/.test(
+        name
+      )
+    )
+
+    expect(fieldSizes).toEqual([])
+    /* filter chips keep Material's size on the platform; ox-input-select-buttons sizes its own */
+    expect(theme['--md-filter-chip-container-height']).toBeUndefined()
+  })
+})

package/tests/error-colour-contrast.test.ts

@@ -0,0 +1,72 @@
+/**
+ * Error text has to be readable - on its own container, as a filled chip, and on the page.
+ *
+ * Until 2026-09-17 it was not: light `error` on `surface` measured 2.95 and `on-error-container`
+ * on `error-container` 2.41; dark `on-error` on `error` and `on-error-container` on
+ * `error-container` were both 1.75. WCAG 1.4.3 asks 4.5 for text. A refusal message drawn in the
+ * error colour was the hardest line on the screen to read, on exactly the screens where reading it
+ * matters.
+ *
+ * The fix kept each colour's OKLCH hue and chroma and only moved lightness, so red is still the
+ * same red - only darker where it sits on light, and a dark red under the pink in dark mode.
+ *
+ * Every app without its own light.css / dark.css receives these values, so this is a platform-wide
+ * change on purpose: a failing contrast is a defect, not a choice.
+ */
+
+import { readFileSync } from 'fs'
+import path from 'path'
+
+const THEMES = path.resolve(__dirname, '../client/themes')
+
+/** WCAG 1.4.3 minimum for normal text. */
+const TEXT = 4.5
+
+function slotsOf(file: string): Map<string, string> {
+  const css = readFileSync(path.join(THEMES, file), 'utf-8')
+  return new Map([...css.matchAll(/--md-sys-color-([a-z-]+)\s*:\s*([^;]+);/g)].map(m => [m[1], m[2].trim()]))
+}
+
+/** Accepts `#rrggbb` and `rgb(r g b)`; a `var(--x, <colour>)` resolves to its fallback. */
+function rgbOf(value: string): [number, number, number] {
+  const fallback = value.match(/^var\(--[a-z-]+, (.*)\)$/)
+  const v = fallback ? fallback[1] : value
+
+  const hex = v.match(/^#([0-9a-fA-F]{2})([0-9a-fA-F]{2})([0-9a-fA-F]{2})$/)
+  if (hex) return [parseInt(hex[1], 16), parseInt(hex[2], 16), parseInt(hex[3], 16)]
+
+  const rgb = v.match(/^rgb\((\d+)\s+(\d+)\s+(\d+)\)$/)
+  if (rgb) return [Number(rgb[1]), Number(rgb[2]), Number(rgb[3])]
+
+  throw new Error(`cannot read colour: ${value}`)
+}
+
+function luminance([r, g, b]: [number, number, number]): number {
+  const lin = (c: number) => {
+    const s = c / 255
+    return s <= 0.04045 ? s / 12.92 : ((s + 0.055) / 1.055) ** 2.4
+  }
+  return 0.2126 * lin(r) + 0.7152 * lin(g) + 0.0722 * lin(b)
+}
+
+function contrast(a: string, b: string): number {
+  const [hi, lo] = [luminance(rgbOf(a)), luminance(rgbOf(b))].sort((x, y) => y - x)
+  return (hi + 0.05) / (lo + 0.05)
+}
+
+/** [text slot, background slot] - where the error colour is read as text. */
+const PAIRS: [string, string][] = [
+  ['on-error', 'error'],
+  ['on-error-container', 'error-container'],
+  ['error', 'surface'],
+  ['error', 'surface-container-highest']
+]
+
+describe.each(['light.css', 'dark.css'])('error colours in shell %s', file => {
+  const slots = slotsOf(file)
+
+  it.each(PAIRS)('%s on %s reaches 4.5:1', (text, background) => {
+    expect(slots.has(text) && slots.has(background)).toBe(true)
+    expect(contrast(slots.get(text)!, slots.get(background)!)).toBeGreaterThanOrEqual(TEXT)
+  })
+})

package/tests/md-sys-slot-owners.test.ts

@@ -0,0 +1,100 @@
+/**
+ * Who may set each md-sys colour slot - decided by the shell theme, not by a document.
+ *
+ * ── Why the shell opens slots instead of apps replacing files ─────────────────
+ * The theme plugin replaces a stylesheet by file name, so an app that ships its own `light.css`
+ * takes all 49 slots: neutrals, outline, error. Products then disagree on what grey and red mean, and
+ * a fix to the shared `light.css` silently never reaches them. Ordering cannot fix it either: the
+ * plugin puts app files before the shell's, so an app's `.light { --md-sys-color-primary }` loses to
+ * the shell `light.css` behind it at equal specificity (measured on a running app bundle, 2026-09-17).
+ *
+ * So the shell declares slots as `var(--<owner>-<slot>, <shell value>)`. Custom properties resolve at
+ * compute time, so bundle order stops mattering, and a slot that is not opened cannot be reached.
+ *
+ * Three owners, one mechanism - no reliance on bundle order or specificity:
+ *   --brand-<slot>   a product's accent (its own brand.css)                26 slots
+ *   --suite-<slot>   the operato suite's shared greys (@things-factory/operato-suite)  17 slots
+ *   closed           error x4, shadow, scrim - literal, nobody above the platform sets them  6 slots
+ * A tenant's domain theme still wins over all of these: it writes --md-sys-color-* directly, later in
+ * the bundle. Apps with neither brand.css nor the suite get the fallbacks, the shell values of before.
+ *
+ * If md adds a slot the counts go red on purpose: someone has to decide whose it is.
+ */
+
+import { readFileSync } from 'fs'
+import path from 'path'
+
+const THEMES = path.resolve(__dirname, '../client/themes')
+
+const ACCENTS = ['primary', 'secondary', 'tertiary']
+
+const BRAND = new Set([
+  ...ACCENTS.flatMap(a => [
+    a,
+    `on-${a}`,
+    `${a}-container`,
+    `on-${a}-container`,
+    `${a}-fixed`,
+    `on-${a}-fixed`,
+    `${a}-fixed-dim`,
+    `on-${a}-fixed-variant`
+  ]),
+  'surface-tint',
+  'inverse-primary'
+])
+
+const SUITE = new Set([
+  'background',
+  'on-background',
+  'surface',
+  'on-surface',
+  'surface-variant',
+  'on-surface-variant',
+  'outline',
+  'outline-variant',
+  'inverse-surface',
+  'inverse-on-surface',
+  'surface-dim',
+  'surface-bright',
+  'surface-container-lowest',
+  'surface-container-low',
+  'surface-container',
+  'surface-container-high',
+  'surface-container-highest'
+])
+
+function slotsOf(file: string): Map<string, string> {
+  const css = readFileSync(path.join(THEMES, file), 'utf-8')
+  return new Map([...css.matchAll(/--md-sys-color-([a-z-]+)\s*:\s*([^;]+);/g)].map(m => [m[1], m[2].trim()]))
+}
+
+const opened = (prefix: string, slot: string) =>
+  new RegExp(`^var\\(--${prefix}-${slot}, (#[0-9a-fA-F]{3,8}|rgba?\\([^()]*\\))\\)$`)
+
+describe.each(['light.css', 'dark.css'])('shell %s opens accent to products and neutrals to the suite', file => {
+  const slots = slotsOf(file)
+  const names = [...slots.keys()]
+
+  it('declares 49 slots: 26 brand, 17 suite, 6 closed', () => {
+    expect(BRAND.size).toBe(26)
+    expect(SUITE.size).toBe(17)
+    expect(slots.size).toBe(49)
+    expect(names.filter(s => BRAND.has(s)).length).toBe(26)
+    expect(names.filter(s => SUITE.has(s)).length).toBe(17)
+    expect(names.filter(s => !BRAND.has(s) && !SUITE.has(s)).length).toBe(6)
+  })
+
+  it('reads brand slots from --brand-<slot> and suite slots from --suite-<slot>, each with a colour fallback', () => {
+    for (const [slot, value] of slots) {
+      if (BRAND.has(slot)) expect({ slot, value }).toEqual({ slot, value: expect.stringMatching(opened('brand', slot)) })
+      if (SUITE.has(slot)) expect({ slot, value }).toEqual({ slot, value: expect.stringMatching(opened('suite', slot)) })
+    }
+  })
+
+  it('keeps the closed slots literal', () => {
+    for (const [slot, value] of slots) {
+      if (BRAND.has(slot) || SUITE.has(slot)) continue
+      expect({ slot, value }).toEqual({ slot, value: expect.not.stringContaining('var(') })
+    }
+  })
+})

package/tests/popup-buttons-class-shrinks.test.ts

@@ -0,0 +1,83 @@
+/**
+ * The `.buttons` row of CommonPopupStyles is on its way out; this list may only shrink.
+ *
+ * ── Why ──────────────────────────────────────────────────────────────────────
+ * Popup command rows were written as markup under a CSS convention (`<div class="buttons">`), and
+ * nine different rows grew out of that. The row is now an element, `<ox-popup-actions>` from
+ * @operato/popup, which owns order, height, shape and the destructive colour.
+ *
+ * Until every popup has moved, the old rule and the element coexist. Two things keep that from
+ * becoming permanent:
+ *
+ * - a file on this list that no longer uses `.buttons` fails - the move happened, so the list must
+ *   say so (a list that is never updated stops watching anything);
+ * - a file not on this list that starts using `.buttons` fails - new popups use the element.
+ *
+ * When the list is empty here, and in operato-application's own copy of this test, the `.buttons`
+ * rule itself is removed from @operato/styles.
+ *
+ * This test reads only this repository. Each repository keeps its own list.
+ */
+
+import { readdirSync, readFileSync, statSync } from 'fs'
+import path from 'path'
+
+const REPO_ROOT = path.resolve(__dirname, '../../..')
+const PACKAGES = path.join(REPO_ROOT, 'packages')
+
+const SKIP = new Set(['node_modules', 'dist', 'dist-client', 'dist-server', 'dist-shared', 'coverage'])
+
+/** Files that still render the CommonPopupStyles `.buttons` row, as of 2026-09-17. */
+const STILL_USING = [
+  'auth-ui/client/components/app-binding-detail.ts',
+  'auth-ui/client/components/appliance-editor.ts',
+  'auth-ui/client/components/application-editor.ts',
+  'organization/client/component/approval-line-items-editor-popup.ts',
+  'organization/client/component/approval-line-selector.ts',
+  'organization/client/component/assignees-editor-popup.ts',
+  'organization/client/component/department-selector.ts',
+  'organization/client/component/recipients-editor-popup.ts'
+]
+
+function clientSources(dir: string, found: string[] = []): string[] {
+  for (const entry of readdirSync(dir)) {
+    if (SKIP.has(entry) || entry.startsWith('.')) continue
+
+    const full = path.join(dir, entry)
+    let stat
+    try {
+      stat = statSync(full)
+    } catch {
+      continue
+    }
+
+    if (stat.isDirectory()) clientSources(full, found)
+    else if (entry.endsWith('.ts') && full.includes(`${path.sep}client${path.sep}`)) found.push(full)
+  }
+  return found
+}
+
+/** Uses the row: takes CommonPopupStyles and renders an element with the `buttons` class. */
+function usesButtonsRow(source: string): boolean {
+  return /\bCommonPopupStyles\b/.test(source) && /class\s*=\s*["'](?:[^"']*\s)?buttons(?:\s[^"']*)?["']/.test(source)
+}
+
+describe('the CommonPopupStyles .buttons row only shrinks', () => {
+  const files = clientSources(PACKAGES)
+  const using = files
+    .filter(file => usesButtonsRow(readFileSync(file, 'utf-8')))
+    .map(file => path.relative(PACKAGES, file).split(path.sep).join('/'))
+    .sort()
+
+  it('scanned enough client sources for the answer to mean something', () => {
+    expect(files.length).toBeGreaterThanOrEqual(800)
+  })
+
+  it('has no file on the list that already moved to ox-popup-actions', () => {
+    expect(STILL_USING.filter(file => !using.includes(file))).toEqual([])
+  })
+
+  it('has no new file using the row', () => {
+    expect(using.filter(file => !STILL_USING.includes(file))).toEqual([])
+  })
+})