npm - @crossworks/share-ui - Versions diffs - 0.230.43 - Mend

@crossworks/share-ui 0.230.43

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (44) hide show

package/LICENSE.md +135 -0
package/package.json +68 -0
package/src/app-bridge-protocol.ts +115 -0
package/src/app-presenter.tsx +25 -0
package/src/app-sandbox.tsx +552 -0
package/src/appearance.ts +192 -0
package/src/avatar.test.ts +229 -0
package/src/avatar.ts +731 -0
package/src/backgrounds.test.ts +119 -0
package/src/backgrounds.ts +118 -0
package/src/draw-presenter.tsx +39 -0
package/src/event-presenter.tsx +62 -0
package/src/file-presenter.tsx +76 -0
package/src/formula-calculator.tsx +209 -0
package/src/formula-presenter.test.ts +128 -0
package/src/formula-presenter.tsx +301 -0
package/src/help-topics.ts +104 -0
package/src/lib/ink-audit.test.ts +314 -0
package/src/lib/theme-css-blocks.ts +26 -0
package/src/lib/theme-generator.test.ts +179 -0
package/src/lib/theme-registry.gen.ts +352 -0
package/src/lib/themes.test.ts +308 -0
package/src/lib/themes.ts +75 -0
package/src/lib/utils.ts +6 -0
package/src/nav-items.ts +225 -0
package/src/note-presenter.tsx +14 -0
package/src/page-outline.tsx +127 -0
package/src/table-presenter.tsx +226 -0
package/src/task-presenter.tsx +60 -0
package/src/ui/button.tsx +50 -0
package/src/ui/input.tsx +18 -0
package/src/ui/label.tsx +20 -0
package/src/view-payload.ts +82 -0
package/styles/app.css +1098 -0
package/styles/themes.css +6198 -0
package/themes/generate.d.mts +11 -0
package/themes/generate.mjs +618 -0
package/themes/model.d.mts +24 -0
package/themes/model.mjs +213 -0
package/themes/preview.html +145 -0
package/themes/seeds.d.mts +16 -0
package/themes/seeds.mjs +3694 -0
package/tsconfig.json +15 -0
package/tsconfig.tsbuildinfo +1 -0

package/src/appearance.ts ADDED Viewed

@@ -0,0 +1,192 @@
+import { DEFAULT_COLOR_THEME } from './lib/themes';
+import {
+  DEFAULT_AVATAR_STYLE,
+  DEFAULT_AVATAR_TINT,
+  resolveAvatarStyle,
+  resolveAvatarTint,
+} from './avatar';
+import { decodeBackgrounds, encodeBackgrounds } from './backgrounds';
+import {
+  DEFAULT_FONT_SIZE,
+  DEFAULT_LOGO_FONT,
+  DEFAULT_PROSE_FONT,
+  DEFAULT_TITLE_FONT,
+  DEFAULT_UI_FONT,
+  fontByKey,
+  resolveFontSize,
+  resolveFontVars,
+  type ResolvedFontVars,
+} from '@mantle/client-types/display-fonts';
+/**
+ * The brain's system-wide appearance — colour theme, the four fonts and their
+ * four sizes, the avatar style and tint, the generated backgrounds — as it
+ * travels from the anchor owner's profile row to a rendered document.
+ *
+ * There is ONE delivery mechanism: the values are rendered into the `<html>`
+ * tag as attributes (`data-color-theme`, `data-font-logo`, `data-font-title`,
+ * `data-font-ui`, `data-font-prose`, the four size attributes,
+ * `data-avatar-style`, `data-avatar-tint`) plus the font-family CSS vars as
+ * inline style, server-side, on every surface — the client app's root layout
+ * (fed by the public GET /api/appearance) and the server-rendered share/print
+ * pages (read straight from the DB). No before-paint scripts, no localStorage
+ * cache, no coordination flags: the HTML is simply correct when it arrives, and
+ * the client providers read the attributes back on mount as their initial
+ * state.
+ *
+ * SIZES travel as attributes only, never as resolved numbers, because app.css
+ * owns the multipliers — one place holds the scale, so a TS copy cannot drift
+ * from the CSS that actually paints.
+ *
+ * `resolveAppearanceAttrs` is that projection: defaults and unknown keys
+ * resolve to NOTHING (attribute absent, var unset) so the CSS fallbacks win —
+ * "default" is the absence of the attribute, never a value.
+ */
+export type BrainAppearance = {
+  colorTheme: string | null;
+  fontLogo: string | null;
+  fontTitle: string | null;
+  fontUi: string | null;
+  fontProse: string | null;
+  fontSize: string | null;
+  fontLogoSize: string | null;
+  fontTitleSize: string | null;
+  fontProseSize: string | null;
+  avatarStyle: string | null;
+  avatarTint: string | null;
+  backgrounds: string | null;
+};
+export type AppearanceAttrs = {
+  /** Non-default colour theme id, or undefined (attribute omitted). */
+  colorTheme?: string;
+  /** Non-default, registry-known font keys — the client provider's initial
+   *  state, one per slot. */
+  fontLogo?: string;
+  fontTitle?: string;
+  fontUi?: string;
+  fontProse?: string;
+  /** Non-default sizes. 'medium' is the absence of the attribute; app.css turns
+   *  the interface one into a root font-size and the other three into local
+   *  multipliers. */
+  fontSize?: string;
+  fontLogoSize?: string;
+  fontTitleSize?: string;
+  fontProseSize?: string;
+  /** Non-default avatar style id — the client provider's initial state. */
+  avatarStyle?: string;
+  /** Non-default avatar tint — same contract. */
+  avatarTint?: string;
+  /** Non-default per-area generated backgrounds, as `menu=waves,header=off`.
+   *  Areas on their default are omitted, so the attribute is absent entirely on
+   *  a brain that has never chosen. */
+  backgrounds?: string;
+  /** Resolved font-family values for the four CSS vars (inline style on <html>). */
+  fontVars: ResolvedFontVars;
+};
+/** Attribute name ↔ default key, for the four selectable faces. Only keys that
+ *  actually RESOLVED travel: an unknown key must not become provider state a
+ *  modal would then display as the current choice. */
+const FONT_SLOTS = [
+  ['fontLogo', 'wordmark', DEFAULT_LOGO_FONT],
+  ['fontTitle', 'pageTitle', DEFAULT_TITLE_FONT],
+  ['fontUi', 'ui', DEFAULT_UI_FONT],
+  ['fontProse', 'prose', DEFAULT_PROSE_FONT],
+] as const;
+const SIZE_FIELDS = ['fontSize', 'fontLogoSize', 'fontTitleSize', 'fontProseSize'] as const;
+/**
+ * The `<html>` data-attribute name for every font field, and the CSS var name
+ * for every resolved font-family — THE canonical tables. Two renderers stamp an
+ * appearance onto a document (the client root layout and the server htmlPage),
+ * and the original bug this feature fixed was exactly those two drifting: the
+ * server copy missed `--font-sans` for months and every share rendered in
+ * Inter. Both renderers now consume these projections, so an attribute can no
+ * longer exist in one document and not the other; display-fonts.test.ts holds
+ * the tables complete against AppearanceAttrs itself.
+ */
+const FONT_ATTR_NAMES = [
+  ['data-font-logo', 'fontLogo'],
+  ['data-font-title', 'fontTitle'],
+  ['data-font-ui', 'fontUi'],
+  ['data-font-prose', 'fontProse'],
+  ['data-font-size', 'fontSize'],
+  ['data-logo-size', 'fontLogoSize'],
+  ['data-title-size', 'fontTitleSize'],
+  ['data-prose-size', 'fontProseSize'],
+] as const;
+const FONT_VAR_NAMES = [
+  ['--font-wordmark', 'wordmark'],
+  ['--font-page-title', 'pageTitle'],
+  ['--font-sans', 'ui'],
+  ['--font-prose', 'prose'],
+] as const;
+/** The font data-* attributes of a resolved appearance, ready to spread onto
+ *  `<html>` (client) or serialize into the tag (server). Defaults are already
+ *  absent from AppearanceAttrs, so absence needs no handling here. */
+export function appearanceFontAttrs(a: AppearanceAttrs): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const [attr, field] of FONT_ATTR_NAMES) {
+    const value = a[field];
+    if (value) out[attr] = value;
+  }
+  return out;
+}
+/** The font-family CSS vars of a resolved appearance, for the `<html>` inline
+ *  style. Same single-source contract as appearanceFontAttrs. */
+export function appearanceFontVars(a: AppearanceAttrs): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const [name, key] of FONT_VAR_NAMES) {
+    const value = a.fontVars[key];
+    if (value) out[name] = value;
+  }
+  return out;
+}
+export function resolveAppearanceAttrs(a: BrainAppearance | null | undefined): AppearanceAttrs {
+  const out: AppearanceAttrs = { fontVars: {} };
+  if (!a) return out;
+  if (a.colorTheme && a.colorTheme !== DEFAULT_COLOR_THEME) out.colorTheme = a.colorTheme;
+  out.fontVars = resolveFontVars(a.fontLogo, a.fontTitle, a.fontUi, a.fontProse);
+  for (const [field, varName, defaultKey] of FONT_SLOTS) {
+    const stored = a[field];
+    if (!out.fontVars[varName] || !stored) continue;
+    // Resolve through the registry so a legacy alias travels as the key the
+    // modal can actually show, and a dropped key travels as nothing at all.
+    const face = fontByKey(stored);
+    if (face && face.key !== defaultKey) out[field] = face.key;
+  }
+  for (const field of SIZE_FIELDS) {
+    const stored = a[field];
+    if (!stored) continue;
+    const resolved = resolveFontSize(stored);
+    if (resolved !== DEFAULT_FONT_SIZE) out[field] = resolved;
+  }
+  // Same contract: only a known, non-default style travels. A legacy
+  // boring-avatars id stored before the DiceBear move resolves to a shipped
+  // style here, so the attribute is always something the picker can show.
+  if (a.avatarStyle) {
+    const resolved = resolveAvatarStyle(a.avatarStyle);
+    if (resolved !== DEFAULT_AVATAR_STYLE) out.avatarStyle = resolved;
+  }
+  if (a.avatarTint) {
+    const resolved = resolveAvatarTint(a.avatarTint);
+    if (resolved !== DEFAULT_AVATAR_TINT) out.avatarTint = resolved;
+  }
+  // Round-tripped through decode/encode rather than passed along: that drops
+  // unknown areas and unknown styles, and re-omits anything sitting on its
+  // default. What reaches the document is always something the picker can show.
+  if (a.backgrounds) {
+    const encoded = encodeBackgrounds(decodeBackgrounds(a.backgrounds));
+    if (encoded) out.backgrounds = encoded;
+  }
+  return out;
+}

package/src/avatar.test.ts ADDED Viewed

@@ -0,0 +1,229 @@
+import { describe, expect, it, vi } from 'vitest';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import {
+  AVATAR_CATEGORIES,
+  AVATAR_STYLES,
+  DEFAULT_AVATAR_STYLE,
+  DEFAULT_AVATAR_TINT,
+  resolveAvatarTint,
+  avatarStyleMeta,
+  loadAvatarStyle,
+  renderAvatarSvg,
+  requiresAttribution,
+  resolveAvatarStyle,
+} from './avatar';
+/**
+ * The avatar generator runs in a client component AND in a route handler, so
+ * these assert the properties both tiers depend on: it never throws on stored
+ * input, the theme ramp actually reaches the SVG, and the same seed is the
+ * same bytes (the mobile companion caches on that).
+ */
+/** Clean Slate --chart-1..5, light. Hex, straight out of themes.css. */
+const RAMP = ['#666ed1', '#ae467f', '#ad5700', '#4b830f', '#00889b'];
+const styleJson = (id: string) =>
+  JSON.parse(
+    readFileSync(
+      fileURLToPath(
+        new URL(`../node_modules/@dicebear/styles/dist/${id}.min.json`, import.meta.url),
+      ),
+      'utf8',
+    ),
+  ) as { meta: { source: { name: string }; creator: { name: string }; license: { name: string } } };
+describe('the style registry', () => {
+  it('renders every shipped style', async () => {
+    for (const s of AVATAR_STYLES) {
+      const svg = await renderAvatarSvg({ style: s.id, seed: 'Saskia', size: 48 });
+      expect(svg.startsWith('<svg'), s.id).toBe(true);
+    }
+  });
+  it('has unique ids, a known category each, and a default that exists', () => {
+    const ids = AVATAR_STYLES.map((s) => s.id);
+    expect(new Set(ids).size).toBe(ids.length);
+    expect(ids).toContain(DEFAULT_AVATAR_STYLE);
+    const known = new Set(AVATAR_CATEGORIES.map((c) => c.id));
+    for (const s of AVATAR_STYLES) expect(known, s.id).toContain(s.category);
+  });
+  // Labels are OURS, not DiceBear's. Its `meta.source.name` is unusable as a
+  // picker label: `bottts` and `bottts-neutral` are both "Bottts", `big-ears`
+  // is "Face Generator", and `croodles` is "Croodles - Doodle your face". Ten
+  // styles would have been indistinguishable in the list.
+  it('gives every style a distinct, non-empty label', () => {
+    const labels = AVATAR_STYLES.map((s) => s.label);
+    for (const l of labels) expect(l.trim().length).toBeGreaterThan(0);
+    expect(new Set(labels).size, 'duplicate labels').toBe(labels.length);
+  });
+  // The repo is public and 14 of these styles are CC BY 4.0, which REQUIRES
+  // attribution. If a DiceBear bump relicensed a style or renamed its designer,
+  // our credit would quietly become wrong — so the table is checked against the
+  // bytes actually installed rather than trusted.
+  it('states each style’s real creator and licence', () => {
+    for (const s of AVATAR_STYLES) {
+      const meta = styleJson(s.id).meta;
+      expect(s.creator, `${s.id} creator`).toBe(meta.creator.name);
+      // The package writes a couple of licences with a trailing full stop.
+      expect(s.license, `${s.id} licence`).toBe(meta.license.name.replace(/\.$/, ''));
+    }
+  });
+  it('flags exactly the styles that oblige us to credit someone', () => {
+    for (const s of AVATAR_STYLES) {
+      const free = s.license === 'CC0 1.0' || s.license === 'MIT';
+      expect(requiresAttribution(s), `${s.id} (${s.license})`).toBe(!free);
+    }
+  });
+});
+describe('resolveAvatarStyle', () => {
+  it('passes current ids through', () => {
+    expect(resolveAvatarStyle('rings')).toBe('rings');
+  });
+  // Stored avatars still carry boring-avatars ids; they must keep rendering
+  // something sensible without a data migration.
+  it.each([
+    ['beam', 'thumbs'],
+    ['bauhaus', 'shapes'],
+    ['marble', 'glass'],
+    ['sunset', 'glass'],
+    ['pixel', 'identicon'],
+    ['ring', 'rings'],
+  ])('maps legacy %s → %s', (legacy, expected) => {
+    expect(resolveAvatarStyle(legacy)).toBe(expected);
+  });
+  it('falls back for unknown, empty and nullish ids', () => {
+    for (const v of ['nope', '', null, undefined]) {
+      expect(resolveAvatarStyle(v)).toBe(DEFAULT_AVATAR_STYLE);
+    }
+  });
+  it('always yields metadata, even for junk', () => {
+    expect(avatarStyleMeta('nope').id).toBe(DEFAULT_AVATAR_STYLE);
+  });
+});
+describe('lazy loading', () => {
+  // The sync path exists for React, which cannot await mid-render. It must
+  // report "not yet" rather than throw or render a broken avatar.
+  //
+  // The style cache is module-level and every test above populates it, so a
+  // cold style has to come from a FRESH module instance — otherwise this
+  // silently tests the warm path and would still pass if laziness broke.
+  it('renders nothing synchronously until the style is loaded', async () => {
+    vi.resetModules();
+    const cold = await import('./avatar');
+    expect(cold.isAvatarStyleReady('constellation')).toBe(false);
+    expect(cold.renderAvatarSvgSync({ style: 'constellation', seed: 'x' })).toBeNull();
+    await cold.loadAvatarStyle('constellation');
+    expect(cold.isAvatarStyleReady('constellation')).toBe(true);
+    expect(cold.renderAvatarSvgSync({ style: 'constellation', seed: 'x' })).toContain('<svg');
+  });
+  it('shares one load between concurrent callers', async () => {
+    const [a, b] = await Promise.all([loadAvatarStyle('planets'), loadAvatarStyle('planets')]);
+    expect(a).toBe(b);
+  });
+});
+describe('theming', () => {
+  it('puts the theme ramp in the SVG', async () => {
+    const svg = await renderAvatarSvg({ style: 'shapes', seed: 'Saskia', ramp: RAMP });
+    expect(RAMP.some((c) => svg.includes(c))).toBe(true);
+  });
+  // backgroundColor is a CORE option, so it lands even on styles that declare
+  // no `background` colour group — the minimalist ones that expose only a
+  // shape colour, and the character styles, which expose none at all. Without
+  // that, "theme the background" would be a silent no-op for most of the set.
+  it.each(['rings', 'identicon', 'notionists', 'bottts', 'lorelei'])(
+    'themes %s, which declares no background group',
+    async (style) => {
+      const svg = await renderAvatarSvg({ style, seed: 'Saskia', ramp: RAMP });
+      expect(RAMP.some((c) => svg.includes(c))).toBe(true);
+    },
+  );
+  // DiceBear validates colours as hex and throws on anything else. An avatar
+  // must never be the thing that takes a page down.
+  it('drops non-hex colours instead of throwing', async () => {
+    await expect(
+      renderAvatarSvg({ style: 'rings', seed: 'x', ramp: ['oklch(0.5 0.1 200)'] }),
+    ).resolves.toContain('<svg');
+  });
+});
+describe('tint', () => {
+  it('defaults to mixed and rejects junk', () => {
+    expect(DEFAULT_AVATAR_TINT).toBe('mixed');
+    for (const v of ['nope', '', null, undefined]) expect(resolveAvatarTint(v)).toBe('mixed');
+    for (const v of ['native', 'mixed', 'theme']) expect(resolveAvatarTint(v)).toBe(v);
+  });
+  it('native leaves the ramp out entirely', async () => {
+    const svg = await renderAvatarSvg({
+      style: 'shapes',
+      seed: 'Saskia',
+      ramp: RAMP,
+      tint: 'native',
+    });
+    expect(RAMP.some((c) => svg.includes(c))).toBe(false);
+  });
+  // `theme` repaints the style's own colour groups too, so a style with several
+  // of them lands MORE ramp colours in the SVG than `mixed` does.
+  it('theme paints more of the artwork than mixed', async () => {
+    const count = (svg: string) => RAMP.filter((c) => svg.includes(c)).length;
+    const mixed = await renderAvatarSvg({
+      style: 'shapes',
+      seed: 'Saskia',
+      ramp: RAMP,
+      tint: 'mixed',
+    });
+    const themed = await renderAvatarSvg({
+      style: 'shapes',
+      seed: 'Saskia',
+      ramp: RAMP,
+      tint: 'theme',
+    });
+    expect(count(themed)).toBeGreaterThan(count(mixed));
+  });
+  // The guard that stops `theme` producing an invisible avatar: groups declared
+  // `contrastTo` another group are the legible part drawn ON it (initials text,
+  // the icons glyph, thumbs' eyes and mouth) and DiceBear solves them to black
+  // or white. Painting them from the same ramp as the surface behind them is a
+  // coin-flip on whether the avatar still has a face.
+  it('never repaints a contrastTo group, even on theme', async () => {
+    for (const style of ['initials', 'icons', 'thumbs']) {
+      const svg = await renderAvatarSvg({ style, seed: 'Saskia', ramp: RAMP, tint: 'theme' });
+      const solved = /#000000|#ffffff/i.test(svg);
+      expect(solved, `${style} lost its contrast-solved colour`).toBe(true);
+    }
+  });
+});
+describe('determinism', () => {
+  it('same seed → same bytes', async () => {
+    const a = await renderAvatarSvg({ style: 'loops', seed: 'Remy', size: 40, ramp: RAMP });
+    const b = await renderAvatarSvg({ style: 'loops', seed: 'Remy', size: 40, ramp: RAMP });
+    expect(a).toBe(b);
+  });
+  it('different seeds → different avatars', async () => {
+    const a = await renderAvatarSvg({ style: 'loops', seed: 'Remy' });
+    const b = await renderAvatarSvg({ style: 'loops', seed: 'Saskia' });
+    expect(a).not.toBe(b);
+  });
+  it('honours size', async () => {
+    expect(await renderAvatarSvg({ style: 'shapes', seed: 'x', size: 96 })).toContain('width="96"');
+  });
+});