@kenlo/sds-design-system 0.9.9

package/foundations/text.js

@@ -0,0 +1,22 @@
+/**
+ * Text helpers shared by anything that has to match what someone typed against what is
+ * written on screen.
+ */
+
+/**
+ * Strips case and accents so a search box finds what the reader means.
+ *
+ * "Sao Paulo" should find "São Paulo", and "italia" should find "Itália" — a Brazilian
+ * typing in a hurry does not reach for the dead keys, and a list that punishes them for
+ * it is a list that looks broken. NFD splits each accented letter into the letter and its
+ * mark, and the range dropped here is exactly the combining-marks block.
+ *
+ * This lived in two copies — Select's option filter and Input's country list — which is
+ * how the two would have drifted.
+ */
+export function fold(text) {
+  return String(text ?? '')
+    .normalize('NFD')
+    .replace(/[\u0300-\u036f]/g, '')
+    .toLowerCase();
+}

package/foundations/theme-server.js

@@ -0,0 +1,81 @@
+/**
+ * Server-side theme stamping.
+ *
+ * This module has no DOM reference and is safe to import in a server bundle. It exists
+ * because KDLS applies the theme from the browser, after the page has loaded — which on
+ * a server-rendered site paints the first frame with the wrong theme and corrects it in
+ * front of the visitor. Stamping the attributes into <html> during SSR removes that.
+ *
+ * Ported from kdls-design-system v2.5.1 (0f3edf8) components/Theme/Theme.ts.
+ * Divergences, all deliberate:
+ *   - the server-side half is new; KDLS has no equivalent;
+ *   - `primary`, `secondary`, `tertiary` and `lya` are gone from COLOR_SCHEMES;
+ *   - the radius scheme named `default` is gone and `soft` is the install default;
+ *   - `medium` is present, which KDLS's own RadiusScheme type omitted even though the
+ *     stylesheet defined it, making it unreachable from TypeScript;
+ *   - an unknown value throws instead of being written through, so a stale config
+ *     fails loudly instead of rendering an unstyled page.
+ */
+
+export const THEME_MODES = ['light', 'dark', 'system'];
+
+export const COLOR_SCHEMES = ['neutral', 'leaf', 'sand', 'wood', 'clay',
+  'flower', 'dusk', 'sky', 'sea', 'lake'];
+
+// Ordered by how much corner each one has, which is the order they are shown in and the
+// order KDLS lists them. `soft` is the install default, and a default is stated in
+// DEFAULTS rather than by being first — putting it at the front only made the list read
+// as though it had no order at all.
+export const RADIUS_SCHEMES = ['flat', 'soft', 'medium', 'rounded'];
+
+export const FONT_SCHEMES = ['manrope', 'inter', 'helvetica', 'source-sans',
+  'nunito', 'montserrat'];
+
+/** What a consumer gets by declaring nothing. Matches the :root values in tokens.css. */
+export const DEFAULTS = {
+  theme: 'light',
+  colorScheme: 'neutral',
+  radius: 'soft',
+  font: 'manrope',
+};
+
+export const SLOTS = [
+  ['theme', 'data-theme', THEME_MODES],
+  ['colorScheme', 'data-color-scheme', COLOR_SCHEMES],
+  ['radius', 'data-radius', RADIUS_SCHEMES],
+  ['font', 'data-font', FONT_SCHEMES],
+];
+
+/**
+ * Validates one slot and returns the value to write, or null when there is nothing to
+ * write — either because the caller said nothing, or because the value is the default
+ * and the attribute would be redundant.
+ */
+export function resolveSlot(key, value, allowed) {
+  if (value === undefined || value === null) return null;
+  if (!allowed.includes(value)) {
+    throw new Error(`Unknown ${key}: "${value}". Allowed: ${allowed.join(', ')}`);
+  }
+  return value === DEFAULTS[key] ? null : value;
+}
+
+/**
+ * The data-* attribute string for <html> during SSR. Empty when everything is default.
+ *
+ * `theme: 'system'` is treated as the light default here: the visitor's OS preference
+ * is not knowable on the server, and writing data-theme="system" would select nothing,
+ * since the stylesheet has no rule for it. configureSds resolves it on arrival.
+ */
+export function themeAttributes(config = {}) {
+  const resolved = config.theme === 'system'
+    ? { ...config, theme: DEFAULTS.theme }
+    : config;
+
+  return SLOTS
+    .map(([key, attribute, allowed]) => {
+      const value = resolveSlot(key, resolved[key], allowed);
+      return value === null ? null : `${attribute}="${value}"`;
+    })
+    .filter(Boolean)
+    .join(' ');
+}

package/foundations/theme.js

@@ -0,0 +1,42 @@
+/**
+ * Client-side theme application — the twin of theme-server.js.
+ *
+ * Used for live changes after the page has loaded: the CMS editor's postMessage
+ * channel, a theme switcher, a preview. The first paint should already be correct
+ * because the server stamped it; this module changes it afterwards.
+ *
+ * Validation and default handling are imported, not copied, so the two halves cannot
+ * disagree about what is valid or about what counts as a default.
+ */
+import { SLOTS, DEFAULTS, THEME_MODES, COLOR_SCHEMES, RADIUS_SCHEMES,
+  FONT_SCHEMES, resolveSlot } from './theme-server.js';
+
+/**
+ * Resolves 'system' against the OS preference. This reads the preference once, at call
+ * time — it does not subscribe. A consumer that wants to follow a live OS change calls
+ * configureSds again from its own matchMedia listener.
+ */
+function resolveSystemTheme(value) {
+  if (value !== 'system') return value;
+  if (typeof window === 'undefined' || typeof window.matchMedia !== 'function') {
+    return DEFAULTS.theme;
+  }
+  return window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light';
+}
+
+/**
+ * Applies the configuration to a root element, defaulting to <html>.
+ * An attribute at its default value is removed rather than written, which keeps the
+ * DOM matching what themeAttributes would have stamped for the same configuration.
+ */
+export function configureSds(config = {}, root = document.documentElement) {
+  const resolved = { ...config, theme: resolveSystemTheme(config.theme) };
+
+  for (const [key, attribute, allowed] of SLOTS) {
+    const value = resolveSlot(key, resolved[key], allowed);
+    if (value === null) root.removeAttribute(attribute);
+    else root.setAttribute(attribute, value);
+  }
+}
+
+export { DEFAULTS, THEME_MODES, COLOR_SCHEMES, RADIUS_SCHEMES, FONT_SCHEMES };