npm - @quo-systems/ui - Versions diffs - 0.1.0 → 0.1.1 - Mend

@quo-systems/ui 0.1.0 → 0.1.1

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 (6) hide show

package/dist/elements/theme.d.ts CHANGED Viewed

@@ -1,9 +1,3 @@
-export declare const THEME_KEY = "nv.theme";
+export declare const THEME_COOKIE = "nv.theme";
 export declare const prepaint: string;
 export declare function applyTheme(value: string, root: HTMLElement): void;
-export declare class NvTheme extends HTMLElement {
-    connectedCallback(): void;
-    disconnectedCallback(): void;
-    handleEvent(event: Event): void;
-    private mark;
-}

package/dist/elements/theme.js CHANGED Viewed

@@ -8,32 +8,58 @@
 // still labelled, and the page still paints, because `auto` is the state a
 // document in no theme is already in.
 //
-// The store is one key, so the app, the screen and a website all read the
-// same choice on the same origin.
-export const THEME_KEY = 'nv.theme';
+// The choice is a cookie and not browser storage, and that is the whole
+// reason this element exists rather than three lines in a page. A cookie
+// carries a Domain, so a person who picks dark on a world's website has
+// picked dark on its quo subdomain and in its app: one choice, one surface
+// to them, however many origins it is to us. Browser storage is per origin
+// and would make each of those a stranger to the others.
+//
+// A server may read it too, since a cookie is sent with the request, but
+// nothing here needs that: the snippet below runs before the first paint
+// and no page waits on it.
+export const THEME_COOKIE = 'nv.theme';
 // Inline this in <head>, before any stylesheet, or the first paint is the
 // wrong theme and the second one is a flash. It is the only script the kit
 // asks a page to inline, and it is this short on purpose.
-export const prepaint = `try{var t=localStorage.getItem(${JSON.stringify(THEME_KEY)});` +
-    `if(t&&t!=='auto')document.documentElement.dataset.theme=t}catch(e){}`;
-// Storage is gone in a private window, cleared by a browser that blocks site
-// data, and throws outright in some embeddings. A theme control is a
-// convenience, so every read and write fails quietly and the surface stays
-// on `auto`.
-function stored() {
+export const prepaint = `try{var m=document.cookie.match(/(?:^|; )${THEME_COOKIE.replace('.', '\\.')}=([^;]*)/);` +
+    `if(m&&m[1]!=='auto')document.documentElement.dataset.theme=decodeURIComponent(m[1])}catch(e){}`;
+function stored(doc) {
     try {
-        return localStorage.getItem(THEME_KEY);
+        const m = doc.cookie.match(new RegExp(`(?:^|; )${THEME_COOKIE.replace('.', '\\.')}=([^;]*)`));
+        return m ? decodeURIComponent(m[1]) : null;
     }
     catch {
         return null;
     }
 }
-function store(value) {
+/*
+ * The domain a choice is remembered for: the registrable one, so every
+ * subdomain of a world shares it. Two labels, which is right for every name
+ * this repository serves and wrong for a two-label public suffix such as
+ * `co.uk`; a world under one of those sets its own Domain and this is where
+ * that would be read from.
+ *
+ * A bare host or an address gets no Domain at all, because a browser rejects
+ * one there and would drop the cookie entirely.
+ */
+function domainOf(host) {
+    if (!host || host === 'localhost' || /^[\d.]+$/.test(host) || !host.includes('.'))
+        return null;
+    return `.${host.split('.').slice(-2).join('.')}`;
+}
+function store(value, doc) {
     try {
-        if (value === 'auto')
-            localStorage.removeItem(THEME_KEY);
-        else
-            localStorage.setItem(THEME_KEY, value);
+        const parts = [
+            `${THEME_COOKIE}=${encodeURIComponent(value)}`,
+            'Path=/',
+            'SameSite=Lax',
+            'Max-Age=31536000',
+        ];
+        const domain = domainOf(doc.location?.hostname ?? '');
+        if (domain)
+            parts.push(`Domain=${domain}`);
+        doc.cookie = parts.join('; ');
     }
     catch {
         /* a choice that cannot be remembered still applies to this page */
@@ -45,31 +71,40 @@ export function applyTheme(value, root) {
     else
         root.dataset.theme = value;
 }
-export class NvTheme extends HTMLElement {
-    connectedCallback() {
-        this.addEventListener('click', this);
-        this.mark(stored() ?? 'auto');
-    }
-    disconnectedCallback() {
-        this.removeEventListener('click', this);
-    }
-    handleEvent(event) {
-        const button = event.target?.closest('[data-theme]');
-        if (!button || !this.contains(button))
-            return;
-        const chosen = button.dataset.theme ?? 'auto';
-        store(chosen);
-        this.mark(chosen);
-    }
-    // The document and the buttons say the same thing, always, and the element
-    // is the only writer of either.
-    mark(chosen) {
-        applyTheme(chosen, this.ownerDocument.documentElement);
-        for (const button of this.querySelectorAll('[data-theme]')) {
-            button.setAttribute('aria-pressed', String(button.dataset.theme === chosen));
+/*
+ * The class is built inside this function and not at the top of the file,
+ * so importing this module where there is no DOM is safe. A site that
+ * renders on request imports it on the server to inline `prepaint`, and a
+ * class extending HTMLElement at module scope would end that render with a
+ * ReferenceError before a page ever reached a browser.
+ */
+function define() {
+    if (typeof customElements === 'undefined' || customElements.get('nv-theme'))
+        return;
+    customElements.define('nv-theme', class extends HTMLElement {
+        connectedCallback() {
+            this.addEventListener('click', this);
+            this.mark(stored(this.ownerDocument) ?? 'auto');
         }
-    }
-}
-if (typeof customElements !== 'undefined' && !customElements.get('nv-theme')) {
-    customElements.define('nv-theme', NvTheme);
+        disconnectedCallback() {
+            this.removeEventListener('click', this);
+        }
+        handleEvent(event) {
+            const button = event.target?.closest('[data-theme]');
+            if (!button || !this.contains(button))
+                return;
+            const chosen = button.dataset.theme ?? 'auto';
+            store(chosen, this.ownerDocument);
+            this.mark(chosen);
+        }
+        // The document and the buttons say the same thing, always, and the
+        // element is the only writer of either.
+        mark(chosen) {
+            applyTheme(chosen, this.ownerDocument.documentElement);
+            for (const button of this.querySelectorAll('[data-theme]')) {
+                button.setAttribute('aria-pressed', String(button.dataset.theme === chosen));
+            }
+        }
+    });
 }
+define();

package/dist/tokens/livery.js CHANGED Viewed

@@ -12,6 +12,37 @@ export function missingSlots(slots) {
 export function forbiddenSlots(slots) {
     return Object.keys(slots).filter((slot) => !designMaySet(slot));
 }
+const declare = (slots, pad) => Object.entries(slots)
+    .map(([slot, value]) => `${pad}${slot}: ${value};`)
+    .join('\n');
+/*
+ * What a document in no theme wears.
+ *
+ * `auto` is not a theme, it is the absence of a choice, and a design whose
+ * every block keys on data-theme paints nothing at all when nobody has
+ * chosen. So the first theme declared is also written at the bare root, and
+ * where a design has both light and dark the system preference picks between
+ * them for a reader who has told their system and not this page.
+ *
+ * The dark block is guarded against an explicit light, or a reader who chose
+ * light on a dark-preferring system would be overruled by their own machine.
+ */
+function systemBlocks(livery) {
+    const themes = Object.entries(livery.themes);
+    const [firstName, first] = themes[0];
+    const out = [
+        `:root {\n  color-scheme: ${first.colorScheme};\n\n${declare(first.slots, '  ')}\n}`,
+    ];
+    const other = themes.find(([name]) => name !== firstName && name === 'dark') ??
+        themes.find(([name]) => name !== firstName);
+    if (themes.length > 1 && other && first.colorScheme !== other[1].colorScheme) {
+        const [, o] = other;
+        out.push(`@media (prefers-color-scheme: ${o.colorScheme}) {\n` +
+            `  :root:not([data-theme='${firstName}']) {\n` +
+            `    color-scheme: ${o.colorScheme};\n\n${declare(o.slots, '    ')}\n  }\n}`);
+    }
+    return out;
+}
 // Throws on the first theme that leaves a required slot undefined or sets one
 // that belongs to the kit. A design either paints a whole face or it does not
 // compile.
@@ -26,14 +57,13 @@ export function renderTokensCss(livery) {
         if (forbidden.length > 0) {
             throw new Error(`${theme}: structure belongs to the kit, and livery.json sets:\n  ${forbidden.join('\n  ')}`);
         }
-        const declared = Object.entries(slots)
-            .map(([slot, value]) => `  ${slot}: ${value};`)
-            .join('\n');
-        blocks.push(`:root[data-theme='${theme}'] {\n  color-scheme: ${colorScheme};\n\n${declared}\n}`);
+        blocks.push(`:root[data-theme='${theme}'] {\n  color-scheme: ${colorScheme};\n\n${declare(slots, '  ')}\n}`);
     }
     return (`/*\n * Generated from livery.json. Never edit: run nv-livery.\n *\n` +
         ` * The ${livery.name} palette, colour and shadow only, worn by whichever\n` +
         ` * estate wears the ${livery.name} design. Declared unlayered, so it wins\n` +
-        ` * over the kit's layered defaults without a specificity trick.\n */\n\n` +
-        `${blocks.join('\n\n')}\n`);
+        ` * over the kit's layered defaults without a specificity trick.\n *\n` +
+        ` * The first block is what a document in no theme wears, since auto is\n` +
+        ` * the absence of a choice and not a theme of its own.\n */\n\n` +
+        `${[...systemBlocks(livery), ...blocks].join('\n\n')}\n`);
 }

package/elements/theme.ts CHANGED Viewed

@@ -8,34 +8,61 @@
 // still labelled, and the page still paints, because `auto` is the state a
 // document in no theme is already in.
 //
-// The store is one key, so the app, the screen and a website all read the
-// same choice on the same origin.
+// The choice is a cookie and not browser storage, and that is the whole
+// reason this element exists rather than three lines in a page. A cookie
+// carries a Domain, so a person who picks dark on a world's website has
+// picked dark on its quo subdomain and in its app: one choice, one surface
+// to them, however many origins it is to us. Browser storage is per origin
+// and would make each of those a stranger to the others.
+//
+// A server may read it too, since a cookie is sent with the request, but
+// nothing here needs that: the snippet below runs before the first paint
+// and no page waits on it.
-export const THEME_KEY = 'nv.theme';
+export const THEME_COOKIE = 'nv.theme';
 // Inline this in <head>, before any stylesheet, or the first paint is the
 // wrong theme and the second one is a flash. It is the only script the kit
 // asks a page to inline, and it is this short on purpose.
 export const prepaint =
-  `try{var t=localStorage.getItem(${JSON.stringify(THEME_KEY)});` +
-  `if(t&&t!=='auto')document.documentElement.dataset.theme=t}catch(e){}`;
+  `try{var m=document.cookie.match(/(?:^|; )${THEME_COOKIE.replace('.', '\\.')}=([^;]*)/);` +
+  `if(m&&m[1]!=='auto')document.documentElement.dataset.theme=decodeURIComponent(m[1])}catch(e){}`;
-// Storage is gone in a private window, cleared by a browser that blocks site
-// data, and throws outright in some embeddings. A theme control is a
-// convenience, so every read and write fails quietly and the surface stays
-// on `auto`.
-function stored(): string | null {
+function stored(doc: Document): string | null {
   try {
-    return localStorage.getItem(THEME_KEY);
+    const m = doc.cookie.match(new RegExp(`(?:^|; )${THEME_COOKIE.replace('.', '\\.')}=([^;]*)`));
+    return m ? decodeURIComponent(m[1]) : null;
   } catch {
     return null;
   }
 }
-function store(value: string): void {
+/*
+ * The domain a choice is remembered for: the registrable one, so every
+ * subdomain of a world shares it. Two labels, which is right for every name
+ * this repository serves and wrong for a two-label public suffix such as
+ * `co.uk`; a world under one of those sets its own Domain and this is where
+ * that would be read from.
+ *
+ * A bare host or an address gets no Domain at all, because a browser rejects
+ * one there and would drop the cookie entirely.
+ */
+function domainOf(host: string): string | null {
+  if (!host || host === 'localhost' || /^[\d.]+$/.test(host) || !host.includes('.')) return null;
+  return `.${host.split('.').slice(-2).join('.')}`;
+}
+function store(value: string, doc: Document): void {
   try {
-    if (value === 'auto') localStorage.removeItem(THEME_KEY);
-    else localStorage.setItem(THEME_KEY, value);
+    const parts = [
+      `${THEME_COOKIE}=${encodeURIComponent(value)}`,
+      'Path=/',
+      'SameSite=Lax',
+      'Max-Age=31536000',
+    ];
+    const domain = domainOf(doc.location?.hostname ?? '');
+    if (domain) parts.push(`Domain=${domain}`);
+    doc.cookie = parts.join('; ');
   } catch {
     /* a choice that cannot be remembered still applies to this page */
   }
@@ -46,34 +73,46 @@ export function applyTheme(value: string, root: HTMLElement): void {
   else root.dataset.theme = value;
 }
-export class NvTheme extends HTMLElement {
-  connectedCallback(): void {
-    this.addEventListener('click', this);
-    this.mark(stored() ?? 'auto');
-  }
+/*
+ * The class is built inside this function and not at the top of the file,
+ * so importing this module where there is no DOM is safe. A site that
+ * renders on request imports it on the server to inline `prepaint`, and a
+ * class extending HTMLElement at module scope would end that render with a
+ * ReferenceError before a page ever reached a browser.
+ */
+function define(): void {
+  if (typeof customElements === 'undefined' || customElements.get('nv-theme')) return;
-  disconnectedCallback(): void {
-    this.removeEventListener('click', this);
-  }
+  customElements.define(
+    'nv-theme',
+    class extends HTMLElement {
+      connectedCallback(): void {
+        this.addEventListener('click', this);
+        this.mark(stored(this.ownerDocument) ?? 'auto');
+      }
-  handleEvent(event: Event): void {
-    const button = (event.target as Element | null)?.closest<HTMLElement>('[data-theme]');
-    if (!button || !this.contains(button)) return;
-    const chosen = button.dataset.theme ?? 'auto';
-    store(chosen);
-    this.mark(chosen);
-  }
+      disconnectedCallback(): void {
+        this.removeEventListener('click', this);
+      }
-  // The document and the buttons say the same thing, always, and the element
-  // is the only writer of either.
-  private mark(chosen: string): void {
-    applyTheme(chosen, this.ownerDocument.documentElement);
-    for (const button of this.querySelectorAll<HTMLElement>('[data-theme]')) {
-      button.setAttribute('aria-pressed', String(button.dataset.theme === chosen));
-    }
-  }
-}
+      handleEvent(event: Event): void {
+        const button = (event.target as Element | null)?.closest<HTMLElement>('[data-theme]');
+        if (!button || !this.contains(button)) return;
+        const chosen = button.dataset.theme ?? 'auto';
+        store(chosen, this.ownerDocument);
+        this.mark(chosen);
+      }
-if (typeof customElements !== 'undefined' && !customElements.get('nv-theme')) {
-  customElements.define('nv-theme', NvTheme);
+      // The document and the buttons say the same thing, always, and the
+      // element is the only writer of either.
+      mark(chosen: string): void {
+        applyTheme(chosen, this.ownerDocument.documentElement);
+        for (const button of this.querySelectorAll<HTMLElement>('[data-theme]')) {
+          button.setAttribute('aria-pressed', String(button.dataset.theme === chosen));
+        }
+      }
+    },
+  );
 }
+define();

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@quo-systems/ui",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "The kit: one token contract, one baseline, and the primitives a screen and a website both need. No framework, no dependency, and no word about harbor, ward or being.",
   "keywords": [
     "design-tokens",

package/tokens/livery.ts CHANGED Viewed

@@ -25,6 +25,42 @@ export function forbiddenSlots(slots: Record<string, string>): string[] {
   return Object.keys(slots).filter((slot) => !designMaySet(slot));
 }
+const declare = (slots: Record<string, string>, pad: string) =>
+  Object.entries(slots)
+    .map(([slot, value]) => `${pad}${slot}: ${value};`)
+    .join('\n');
+/*
+ * What a document in no theme wears.
+ *
+ * `auto` is not a theme, it is the absence of a choice, and a design whose
+ * every block keys on data-theme paints nothing at all when nobody has
+ * chosen. So the first theme declared is also written at the bare root, and
+ * where a design has both light and dark the system preference picks between
+ * them for a reader who has told their system and not this page.
+ *
+ * The dark block is guarded against an explicit light, or a reader who chose
+ * light on a dark-preferring system would be overruled by their own machine.
+ */
+function systemBlocks(livery: Livery): string[] {
+  const themes = Object.entries(livery.themes);
+  const [firstName, first] = themes[0];
+  const out = [
+    `:root {\n  color-scheme: ${first.colorScheme};\n\n${declare(first.slots, '  ')}\n}`,
+  ];
+  const other = themes.find(([name]) => name !== firstName && name === 'dark') ??
+    themes.find(([name]) => name !== firstName);
+  if (themes.length > 1 && other && first.colorScheme !== other[1].colorScheme) {
+    const [, o] = other;
+    out.push(
+      `@media (prefers-color-scheme: ${o.colorScheme}) {\n` +
+        `  :root:not([data-theme='${firstName}']) {\n` +
+        `    color-scheme: ${o.colorScheme};\n\n${declare(o.slots, '    ')}\n  }\n}`,
+    );
+  }
+  return out;
+}
 // Throws on the first theme that leaves a required slot undefined or sets one
 // that belongs to the kit. A design either paints a whole face or it does not
 // compile.
@@ -41,18 +77,17 @@ export function renderTokensCss(livery: Livery): string {
         `${theme}: structure belongs to the kit, and livery.json sets:\n  ${forbidden.join('\n  ')}`,
       );
     }
-    const declared = Object.entries(slots)
-      .map(([slot, value]) => `  ${slot}: ${value};`)
-      .join('\n');
     blocks.push(
-      `:root[data-theme='${theme}'] {\n  color-scheme: ${colorScheme};\n\n${declared}\n}`,
+      `:root[data-theme='${theme}'] {\n  color-scheme: ${colorScheme};\n\n${declare(slots, '  ')}\n}`,
     );
   }
   return (
     `/*\n * Generated from livery.json. Never edit: run nv-livery.\n *\n` +
     ` * The ${livery.name} palette, colour and shadow only, worn by whichever\n` +
     ` * estate wears the ${livery.name} design. Declared unlayered, so it wins\n` +
-    ` * over the kit's layered defaults without a specificity trick.\n */\n\n` +
-    `${blocks.join('\n\n')}\n`
+    ` * over the kit's layered defaults without a specificity trick.\n *\n` +
+    ` * The first block is what a document in no theme wears, since auto is\n` +
+    ` * the absence of a choice and not a theme of its own.\n */\n\n` +
+    `${[...systemBlocks(livery), ...blocks].join('\n\n')}\n`
   );
 }