@fusion.dev/helix-core 0.148.0 → 0.149.0

package/dist/words/words.d.ts

@@ -0,0 +1,52 @@
+import type { ReactiveElement } from 'lit';
+import { type MessageValues } from './message.js';
+/** An element that reads words: a Lit element, perhaps with a `locale`. */
+type Host = ReactiveElement & {
+    locale?: string | undefined;
+};
+/**
+ * Makes a property a word property: one a page can set, register for a
+ * locale with `registerWords`, or leave in English. Written above
+ * `@property`, which declares its attribute:
+ *
+ * ```ts
+ * static words = 'helix-combobox'
+ *
+ * @words
+ * @property({ attribute: 'empty-text' })
+ * emptyText = 'No matches'
+ * ```
+ *
+ * **Reading the property gives the word in the element's locale**: a value
+ * you set, then the words registered for the element's locale, then the
+ * initializer, which is the English. Setting any value, the English included,
+ * makes it yours. Setting `null` or `undefined`, or removing the attribute,
+ * gives the registry's word back. So does an empty validation message, a
+ * property whose name ends in `Message`: a field never reports a failed check
+ * with no sentence, and a template that renders an empty variable into
+ * `range-overflow-message=""` gets the built-in sentence.
+ *
+ * **A subclass or a family that overrides a word's English writes `@words`
+ * above the override**, and its initializer is the English: a family's
+ * `Remove filter` over a mixin's `Dismiss`. Every `@words` declaration has an
+ * initializer, so an element knows how many of its sets are English.
+ *
+ * The class's static `words` names the key its words are registered under, the
+ * family's styled tag, so the headless and styled tiers share one key. A mixin
+ * that declares words writes `static words = ''`, which its host's key
+ * replaces; a host with no key of its own reads its tag name. An element whose
+ * words change updates once, with each changed property named.
+ */
+export declare const words: (proto: object, name: string) => void;
+/**
+ * A word property of an element, formatted: its values put in, its numbers
+ * written in the element's locale, and its plural forms picked by the rules
+ * of the language its words are in. A property no `@words` declares is
+ * formatted as it reads, with the element's own plural rules.
+ *
+ * ```ts
+ * formatWords(this, 'resultsLabel', { count: 3 }) // '3 results'
+ * ```
+ */
+export declare const formatWords: (host: Host, name: string, values?: MessageValues) => string;
+export {};

package/dist/words/words.js

@@ -0,0 +1,100 @@
+import { formatMessage } from './message.js';
+import { lookupWord, watchWords, wordsRegistered } from './registry.js';
+import { wordsLocale } from './words-locale.js';
+const HELD = Symbol();
+const heldBy = (host) => host[HELD] ?? {};
+const declared = new WeakMap();
+const initializers = (host, name) => {
+    let count = 0;
+    for (let proto = Object.getPrototypeOf(host); proto; proto = Object.getPrototypeOf(proto)) {
+        count += declared.get(proto)?.has(name) ? 1 : 0;
+    }
+    return count;
+};
+const resolve = (host, name) => {
+    const word = heldBy(host)[name];
+    if (!word) {
+        return [host[name], ''];
+    }
+    const { e: english, o: own } = word;
+    const table = typeof english === 'object' && english;
+    let found = [own, ''];
+    if (own == null || table) {
+        const registered = wordsRegistered()
+            ? lookupWord(wordsLocale(host), host.constructor.words || host.localName, name)
+            : undefined;
+        found = table
+            ? [{ ...table, ...registered?.[0], ...own }, '']
+            : (registered ?? [english, 'en']);
+    }
+    word.l = found[0];
+    return found;
+};
+const same = (one, two) => one === two || JSON.stringify(one) === JSON.stringify(two);
+const recheck = (host) => {
+    for (const [name, word] of Object.entries(heldBy(host))) {
+        const before = word.l;
+        if ('l' in word && !same(before, resolve(host, name)[0])) {
+            host.requestUpdate(name, before);
+        }
+    }
+};
+const watcher = (host) => {
+    let stop;
+    let locale = '';
+    return {
+        hostConnected: () => {
+            locale = wordsLocale(host);
+            stop = watchWords(() => {
+                recheck(host);
+                const now = wordsLocale(host);
+                if (now !== locale) {
+                    locale = now;
+                    host.requestUpdate();
+                }
+            });
+        },
+        hostDisconnected: () => stop?.(),
+        hostUpdated: () => {
+            if (host.hydrating === true) {
+                queueMicrotask(() => recheck(host));
+            }
+        },
+    };
+};
+export const words = (proto, name) => {
+    if (!Object.getOwnPropertyDescriptor(proto, name)) {
+        ;
+        proto.constructor.createProperty(name);
+    }
+    const names = declared.get(proto) ?? new Set();
+    declared.set(proto, names.add(name));
+    Object.defineProperty(proto, name, {
+        configurable: true,
+        enumerable: true,
+        get() {
+            return resolve(this, name)[0];
+        },
+        set(value) {
+            if (!this[HELD]) {
+                this[HELD] = {};
+                this.addController(watcher(this));
+            }
+            const word = (this[HELD][name] ??= { i: 0 });
+            if (word.i < initializers(this, name)) {
+                word.i++;
+                word.e = value;
+                this.requestUpdate(name, undefined, undefined, true, value);
+                return;
+            }
+            const before = this[name];
+            word.o = value === '' && name.endsWith('Message') ? undefined : value;
+            this.requestUpdate(name, before);
+        },
+    });
+};
+export const formatWords = (host, name, values = {}) => {
+    const [message, from] = resolve(host, name);
+    const locale = wordsLocale(host);
+    return formatMessage(String(message ?? ''), values, locale, { plurals: from || locale });
+};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@fusion.dev/helix-core",
   "description": "Helix element primitives: base classes, mixins, decorators, utilities.",
-  "version": "0.148.0",
+  "version": "0.149.0",
   "license": "MIT",
   "author": "Ross Sheppard <ross.sheppard@fusion.dev>",
   "repository": {
@@ -17,7 +17,29 @@
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
     },
-    "./custom-elements.json": "./custom-elements.json"
+    "./audits/name": {
+      "types": "./dist/utils/audit-name/audit-name.d.ts",
+      "development": "./dist/utils/audit-name/audit-name.js",
+      "helix-development": "./dist/utils/audit-name/audit-name.js",
+      "default": "./dist/utils/audit-name/audit-name-off.js"
+    },
+    "./audits/react": {
+      "types": "./dist/helix-element/react-audit.d.ts",
+      "development": "./dist/helix-element/react-audit.js",
+      "helix-development": "./dist/helix-element/react-audit.js",
+      "default": "./dist/helix-element/react-audit-off.js"
+    },
+    "./audits/source": {
+      "types": "./dist/utils/audit-source/audit-source.d.ts",
+      "development": "./dist/utils/audit-source/audit-source.js",
+      "helix-development": "./dist/utils/audit-source/audit-source.js",
+      "default": "./dist/utils/audit-source/audit-source-off.js"
+    },
+    "./custom-elements.json": "./custom-elements.json",
+    "./words": {
+      "types": "./dist/words/index.d.ts",
+      "default": "./dist/words/index.js"
+    }
   },
   "files": [
     "custom-elements.json",
@@ -27,44 +49,37 @@
   "sideEffects": false,
   "scripts": {
     "analyze": "bun --bun helix-cem",
-    "build": "tsc -p tsconfig.build.json && tsc -p tsconfig.types.json",
-    "test": "bun test src --conditions helix-source --conditions helix-development",
+    "build": "tsc -p tsconfig.build.json && tsc -p tsconfig.types.json && bun scripts/development-imports.mjs",
+    "test": "bun test src --conditions helix-development",
     "typecheck": "tsc -p tsconfig.json --noEmit"
   },
   "bugs": "https://github.com/project-fusion/fusion/issues",
   "dependencies": {
     "@floating-ui/dom": "^1.8.0",
-    "@fusion.dev/helix-icons": "0.148.0"
+    "@fusion.dev/helix-icons": "0.149.0"
   },
   "devDependencies": {
-    "@fusion.dev/helix-cem": "0.148.0",
-    "@fusion.dev/helix-testing": "0.148.0",
+    "@fusion.dev/helix-cem": "0.149.0",
+    "@fusion.dev/helix-testing": "0.149.0",
     "@lit-labs/ssr": "^4.1.0",
     "lit": "^3.2.1"
   },
   "homepage": "https://fusion.dev",
   "imports": {
     "#audit-name": {
-      "helix-source": {
-        "development": "./src/utils/audit-name/audit-name.ts",
-        "helix-development": "./src/utils/audit-name/audit-name.ts",
-        "default": "./src/utils/audit-name/audit-name-off.ts"
-      },
-      "types": "./dist/utils/audit-name/audit-name.d.ts",
-      "development": "./dist/utils/audit-name/audit-name.js",
-      "helix-development": "./dist/utils/audit-name/audit-name.js",
-      "default": "./dist/utils/audit-name/audit-name-off.js"
+      "development": "./src/utils/audit-name/audit-name.ts",
+      "helix-development": "./src/utils/audit-name/audit-name.ts",
+      "default": "./src/utils/audit-name/audit-name-off.ts"
     },
     "#audit-source": {
-      "helix-source": {
-        "development": "./src/utils/audit-source/audit-source.ts",
-        "helix-development": "./src/utils/audit-source/audit-source.ts",
-        "default": "./src/utils/audit-source/audit-source-off.ts"
-      },
-      "types": "./dist/utils/audit-source/audit-source.d.ts",
-      "development": "./dist/utils/audit-source/audit-source.js",
-      "helix-development": "./dist/utils/audit-source/audit-source.js",
-      "default": "./dist/utils/audit-source/audit-source-off.js"
+      "development": "./src/utils/audit-source/audit-source.ts",
+      "helix-development": "./src/utils/audit-source/audit-source.ts",
+      "default": "./src/utils/audit-source/audit-source-off.ts"
+    },
+    "#react-audit": {
+      "development": "./src/helix-element/react-audit.ts",
+      "helix-development": "./src/helix-element/react-audit.ts",
+      "default": "./src/helix-element/react-audit-off.ts"
     }
   },
   "keywords": [