@sylwellsoftware/fray 0.1.0-alpha.1 → 0.3.0

package/themes/README.md

@@ -1,30 +1,84 @@
-# Fray theme custom properties
-
-The alpha supports `@sylwellsoftware/fray/themes/light.css` and
-`@sylwellsoftware/fray/themes/dark.css`. Import one after registering Fray structural
-styles, or scope either bundle with `data-fray-theme`.
-
-Consumers may override the variables after the theme import. The supported
-control contract is:
-
-- typography/spacing: `--base-font-size`, `--ui-font-size`, `--ui-padding`,
-  `--ui-padding-h`, `--ui-padding-v`, `--spacing-small`, `--spacing-medium`;
-- shape/focus: `--ui-border-radius`, `--ui-accent-color`,
-  `--ui-accent-color-highlight`;
-- text/input: `--ui-text-color`, `--ui-input-bg`, `--ui-input-border`,
-  `--ui-input-bg-disabled`, `--ui-input-border-disabled`,
-  `--ui-input-text-color-disabled`, `--input-width`, `--input-shadow`;
-- actions: `--button-background`, `--button-background-hover`,
-  `--button-background-disabled`, `--button-border`,
-  `--button-border-disabled`, `--button-shadow`, `--button-color`,
-  `--toggle-selected-bg`, `--toggle-selected-text`;
-- panels/tabs/toolbars: `--panel-*`, `--panel-padding`, `--toolbar-*`,
-  `--sectionheader-*`, `--tabline-bg`, `--tab-bg-active`;
-- checkbox/error: `--cbx-o-border`, `--cbx-border-radius`, `--error-color`.
-
-The root-default selector uses a zero-specificity `:where(...)` wrapper. The
-explicit `data-fray-theme` selector retains attribute specificity so it also
-wins when an application bundles more than one theme and the other bundle's
-root fallback loads later. A consumer inline custom property or a more-specific
-rule can still override a theme value. Import one bundle for one root default,
-or import multiple bundles and select an explicit theme on each scoped subtree.
+# Fray structural, theme, and color CSS
+
+Fray deliberately separates three stylesheet responsibilities:
+
+1. `@sylwellsoftware/fray/styles/structural.css` contains the generated layout,
+   flow, accessibility mechanics, stable selectors, and custom-property uses
+   for the default `fray-` component hosts.
+2. `@sylwellsoftware/fray/themes/<name>/theme.css` supplies geometry, surface
+   treatment, and semantic theme variables. Supported treatments are `shiny`,
+   `java`, and `minimal`.
+3. `@sylwellsoftware/fray/colors/<name>/colors.css` supplies palette and
+   semantic color variables. Supported palettes are `iceblue`, `ocean`,
+   `green`, `gray`, `orange`, `purple`, `red`, and `yellow`.
+
+Load the three artifacts independently:
+
+```ts
+import '@sylwellsoftware/fray/styles/structural.css'
+import '@sylwellsoftware/fray/colors/ocean/colors.css'
+import '@sylwellsoftware/fray/themes/shiny/theme.css'
+```
+
+`ThemePicker` and `ColorPicker` use the exported `frayThemeOptions` and
+`frayColorOptions` catalogs by default. Each picker updates a separate
+`<link data-fray-stylesheet>` element and the corresponding
+`data-fray-theme`/`data-fray-color` root attribute. Applications may supply
+their own option catalogs and URLs. The defaults resolve against Fray's
+published package layout and therefore work for direct ESM/CDN loading. A
+bundler cannot expose a universal runtime URL for package CSS; bundled
+applications should import or emit each CSS asset as a URL and pass remapped
+options to the pickers.
+
+## Variable hierarchy
+
+The public contract is exported as the machine-readable
+`frayThemeVariableCatalog`. Every entry records its layer, family, value kind,
+description, and optional fallback.
+
+| Level | Representative variables | Purpose |
+| --- | --- | --- |
+| Palette | `--fray-color-primary`, `--fray-color-surface`, `--fray-color-text`, `--fray-color-border`, `--fray-color-focus` | Replaceable color-scheme primitives and semantic colors |
+| Global theme | `--fray-font-*`, `--fray-space-*`, `--fray-radius-*`, `--fray-ui-*` | Shared typography, rhythm, shape, and surface treatment |
+| Generic families | `--fray-header-*`, `--fray-button-*`, `--fray-input-*`, `--fray-panel-*`, `--fray-selection-*` | Defaults inherited by related controls |
+| Family variants | `--fray-table-header-*`, `--fray-panel-header-*`, `--fray-toggle-button-*`, `--fray-tab-button-*`, `--fray-dropdown-trigger-*` | Optional narrow overrides for a theme that differentiates one family member |
+| Component escape hatches | `--fray-checkbox-*`, `--fray-progress-*`, `--fray-dialog-*` | Behavior that is not meaningfully shared with a broader family |
+
+Structural rules use the most-specific variable and fall back through the
+family. A custom table-like component can follow the same pattern:
+
+```css
+my-grid > header {
+  color: var(
+    --my-grid-header-color,
+    var(--fray-table-header-color, var(--fray-header-color))
+  );
+  background: var(
+    --my-grid-header-background,
+    var(--fray-table-header-background, var(--fray-header-background))
+  );
+}
+```
+
+The component now adopts every compatible Fray theme without the theme knowing
+its selector. A theme can still specialize it by assigning
+`--my-grid-header-*` on the component host.
+
+## Selector exceptions
+
+Variables are preferred but not exclusive. A treatment may target stable
+`data-fray-component`, `data-part`, role, and ARIA-state hooks for effects that
+custom properties cannot create alone. Shiny uses scoped pseudo-elements and
+native progress/select pseudo-parts for layered highlights, dropdown arrows,
+checkbox surfaces, headers, and button-like controls. Those decorations use
+`pointer-events: none`, preserve native/ARIA state, and are disabled or reduced
+under forced-colors where the browser's representation is safer.
+
+Theme authors should not target application classes, generated IDs, or
+incidental DOM depth. Color values should remain in `colors.css` whenever
+practical; translucent white/black lighting used to construct a treatment is
+permitted in `theme.css`.
+
+The top-level `themes/light.css` and `themes/dark.css` exports are retained as
+alpha compatibility bundles. New integrations should use the separated paths
+above.

package/themes/java/theme.css

@@ -0,0 +1,140 @@
+@charset "utf-8";
+
+:where(:root), [data-fray-theme="java"] {
+  color-scheme: light;
+  --fray-font-family: Arial, Helvetica, sans-serif;
+  --fray-font-size: 0.875rem;
+  --fray-line-height: 1.15;
+  --fray-control-min-height: 1.75rem;
+  --fray-space-xs: 2px;
+  --fray-space-sm: 4px;
+  --fray-space-md: 8px;
+  --fray-space-lg: 12px;
+  --fray-radius-sm: 0;
+  --fray-radius-md: 0;
+  --fray-radius-lg: 3px;
+  --fray-motion-fast: 0ms;
+
+  --fray-ui-background: var(--fray-color-surface-muted);
+  --fray-ui-color: var(--fray-color-text);
+  --fray-ui-border: 1px solid var(--fray-color-border-strong);
+  --fray-ui-shadow: none;
+  --fray-focus-ring: 0 0 0 1px var(--fray-color-focus);
+
+  --fray-panel-background: var(--fray-color-surface-muted);
+  --fray-panel-color: var(--fray-color-text);
+  --fray-panel-border: 2px groove var(--fray-color-highlight);
+  --fray-panel-shadow: none;
+  --fray-panel-radius: 0;
+  --fray-dialog-shadow: 3px 3px 0 color-mix(in srgb, var(--fray-color-shadow) 45%, transparent);
+  --fray-dialog-backdrop-background: color-mix(in srgb, var(--fray-color-shadow) 45%, transparent);
+
+  --fray-header-background: transparent;
+  --fray-header-color: var(--fray-color-text);
+  --fray-header-border: 0 solid transparent;
+  --fray-header-shadow: none;
+  --fray-table-header-background: var(--fray-color-surface-raised);
+  --fray-dialog-header-background: linear-gradient(to bottom, var(--fray-color-primary-active), var(--fray-color-primary));
+
+  --fray-button-background: var(--fray-color-surface-muted);
+  --fray-button-background-hover: var(--fray-color-primary-soft);
+  --fray-button-background-active: var(--fray-color-surface-inset);
+  --fray-button-background-disabled: var(--fray-color-disabled);
+  --fray-button-color: var(--fray-color-text);
+  --fray-button-border: 2px outset var(--fray-color-highlight);
+  --fray-button-shadow: none;
+  --fray-button-shadow-active: none;
+
+  --fray-input-background: var(--fray-color-surface-raised);
+  --fray-input-color: var(--fray-color-text);
+  --fray-input-border: 1px solid var(--fray-color-border-strong);
+  --fray-input-shadow: inset 1px 1px 1px color-mix(in srgb, var(--fray-color-shadow) 30%, transparent);
+  --fray-input-background-disabled: var(--fray-color-disabled);
+  --fray-input-color-disabled: var(--fray-color-on-disabled);
+
+  --fray-selection-background: var(--fray-color-selection);
+  --fray-selection-color: var(--fray-color-on-selection);
+  --fray-row-hover-background: var(--fray-color-primary-soft);
+  --fray-table-row-background: var(--fray-color-surface-raised);
+  --fray-table-row-alt-background: var(--fray-color-surface-raised);
+  --fray-checkbox-box-background: var(--fray-color-surface-raised);
+  --fray-checkbox-box-background-checked: var(--fray-color-selection);
+  --fray-checkbox-box-border: 2px inset var(--fray-color-highlight);
+  --fray-checkbox-symbol-color: var(--fray-color-on-selection);
+  --fray-radio-background: var(--fray-button-background);
+  --fray-radio-background-checked: var(--fray-selection-background);
+  --fray-toolbar-background: var(--fray-color-surface-muted);
+  --fray-toolbar-color: var(--fray-color-text);
+  --fray-toolbar-border: 2px outset var(--fray-color-highlight);
+  --fray-toolbar-shadow: none;
+  --fray-tabline-background: var(--fray-color-surface-muted);
+  --fray-tab-active-background: var(--fray-panel-background);
+  --fray-tab-button-background: var(--fray-color-surface-muted);
+  --fray-progress-track-background: var(--fray-color-surface-inset);
+  --fray-progress-value-background: var(--fray-color-primary);
+  --fray-working-background-image: repeating-linear-gradient(135deg, transparent 0 4px, color-mix(in srgb, var(--fray-color-text) 12%, transparent) 4px 8px);
+
+  --base-font-size: var(--fray-font-size);
+  --ui-font-size: var(--fray-font-size);
+  --ui-padding: var(--fray-space-sm);
+  --ui-padding-h: var(--fray-space-sm);
+  --ui-padding-v: var(--fray-space-xs);
+  --ui-border-radius: var(--fray-radius-md);
+  --ui-text-color: var(--fray-ui-color);
+  --ui-muted-text-color: var(--fray-color-text-muted);
+  --ui-border-color: var(--fray-color-border);
+  --ui-input-bg: var(--fray-input-background);
+  --ui-input-border: var(--fray-input-border);
+  --ui-input-bg-disabled: var(--fray-input-background-disabled);
+  --ui-input-border-disabled: 1px solid var(--fray-color-border);
+  --ui-input-text-color-disabled: var(--fray-input-color-disabled);
+  --ui-accent-color: var(--fray-color-primary);
+  --ui-accent-color-highlight: var(--fray-color-primary-soft);
+  --input-width: 15rem;
+  --input-shadow: var(--fray-input-shadow);
+  --button-background: var(--fray-button-background);
+  --button-background-hover: var(--fray-button-background-hover);
+  --button-background-disabled: var(--fray-button-background-disabled);
+  --button-border: var(--fray-button-border);
+  --button-border-disabled: 1px solid var(--fray-color-border);
+  --button-shadow: var(--fray-button-shadow);
+  --button-color: var(--fray-button-color);
+  --toggle-selected-bg: var(--fray-selection-background);
+  --toggle-selected-text: var(--fray-selection-color);
+  --panel-bg: var(--fray-panel-background);
+  --panel-border: var(--fray-panel-border);
+  --panel-radius: var(--fray-panel-radius);
+  --panel-shadow: var(--fray-panel-shadow);
+  --panel-color: var(--fray-panel-color);
+  --panel-padding: var(--fray-space-md);
+  --toolbar-bg: var(--fray-toolbar-background);
+  --toolbar-border: var(--fray-toolbar-border);
+  --toolbar-radius: var(--fray-radius-lg);
+  --toolbar-shadow: var(--fray-toolbar-shadow);
+  --toolbar-color: var(--fray-toolbar-color);
+  --sectionheader-bg: var(--fray-section-header-background, var(--fray-header-background));
+  --sectionheader-shadow: var(--fray-header-shadow);
+  --sectionheader-color: var(--fray-header-color);
+  --tabline-bg: var(--fray-tabline-background);
+  --tab-bg-active: var(--fray-tab-active-background);
+  --error-color: var(--fray-color-error);
+  --cbx-o-border: var(--fray-checkbox-box-border);
+  --cbx-border-radius: 0;
+  --spacing-small: var(--fray-space-sm);
+  --spacing-medium: var(--fray-space-md);
+  --noselect-user-select: none;
+  --noselect-cursor: default;
+}
+
+:where(:root:not([data-fray-theme]), [data-fray-theme="java"]) :where(
+  button[data-fray-component="button"],
+  [role="tab"],
+  [role="radio"],
+  [role="checkbox"]
+):active {
+  border-style: inset;
+}
+
+:where(:root:not([data-fray-theme]), [data-fray-theme="java"]) [data-fray-component="tab-line"] > [role="tab"][aria-selected="true"] {
+  border-bottom-color: var(--fray-tab-active-background);
+}

package/themes/minimal/theme.css

@@ -0,0 +1,128 @@
+@charset "utf-8";
+
+:where(:root), [data-fray-theme="minimal"] {
+  color-scheme: light;
+  --fray-font-family: Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+  --fray-font-size: 0.875rem;
+  --fray-line-height: 1.25;
+  --fray-control-min-height: 2rem;
+  --fray-space-xs: 0.25rem;
+  --fray-space-sm: 0.5rem;
+  --fray-space-md: 1rem;
+  --fray-space-lg: 1.5rem;
+  --fray-radius-sm: 0.2rem;
+  --fray-radius-md: 0.375rem;
+  --fray-radius-lg: 0.5rem;
+  --fray-motion-fast: 120ms;
+
+  --fray-ui-background: var(--fray-color-surface);
+  --fray-ui-color: var(--fray-color-text);
+  --fray-ui-border: 1px solid var(--fray-color-border);
+  --fray-ui-shadow: none;
+  --fray-focus-ring: 0 0 0 2px var(--fray-color-focus);
+
+  --fray-panel-background: var(--fray-color-surface);
+  --fray-panel-color: var(--fray-color-text);
+  --fray-panel-border: 1px solid var(--fray-color-border);
+  --fray-panel-shadow: none;
+  --fray-panel-radius: var(--fray-radius-md);
+  --fray-dialog-shadow: 0 1.25rem 4rem color-mix(in srgb, var(--fray-color-shadow) 35%, transparent);
+  --fray-dialog-backdrop-background: color-mix(in srgb, var(--fray-color-shadow) 55%, transparent);
+
+  --fray-header-background: var(--fray-color-surface-muted);
+  --fray-header-color: var(--fray-color-text);
+  --fray-header-border: 0 solid transparent;
+  --fray-header-shadow: none;
+  --fray-table-header-background: var(--fray-color-surface-muted);
+
+  --fray-button-background: var(--fray-color-surface-muted);
+  --fray-button-background-hover: var(--fray-color-primary-soft);
+  --fray-button-background-active: var(--fray-color-primary);
+  --fray-button-background-disabled: var(--fray-color-disabled);
+  --fray-button-color: var(--fray-color-text);
+  --fray-button-border: 1px solid var(--fray-color-border-strong);
+  --fray-button-shadow: none;
+  --fray-button-shadow-active: none;
+
+  --fray-input-background: var(--fray-color-surface-raised);
+  --fray-input-color: var(--fray-color-text);
+  --fray-input-border: 1px solid var(--fray-color-border-strong);
+  --fray-input-shadow: none;
+  --fray-input-background-disabled: var(--fray-color-disabled);
+  --fray-input-color-disabled: var(--fray-color-on-disabled);
+
+  --fray-selection-background: var(--fray-color-selection);
+  --fray-selection-color: var(--fray-color-on-selection);
+  --fray-row-hover-background: var(--fray-color-primary-soft);
+  --fray-table-row-background: var(--fray-color-surface);
+  --fray-table-row-alt-background: var(--fray-color-surface-muted);
+
+  --fray-checkbox-box-background: var(--fray-color-surface-raised);
+  --fray-checkbox-box-background-checked: var(--fray-color-selection);
+  --fray-checkbox-box-border: 1px solid var(--fray-color-border-strong);
+  --fray-checkbox-symbol-color: var(--fray-color-on-selection);
+  --fray-radio-background: var(--fray-button-background);
+  --fray-radio-background-checked: var(--fray-selection-background);
+
+  --fray-toolbar-background: var(--fray-color-surface-muted);
+  --fray-toolbar-color: var(--fray-color-text);
+  --fray-toolbar-border: 0 solid transparent;
+  --fray-toolbar-shadow: none;
+  --fray-tabline-background: var(--fray-color-surface-muted);
+  --fray-tab-active-background: var(--fray-color-surface);
+  --fray-progress-track-background: var(--fray-color-surface-inset);
+  --fray-progress-value-background: var(--fray-color-primary);
+  --fray-working-background-image: linear-gradient(-45deg, transparent 25%, color-mix(in srgb, var(--fray-color-highlight) 35%, transparent) 25% 50%, transparent 50% 75%, color-mix(in srgb, var(--fray-color-highlight) 35%, transparent) 75%);
+
+  /* Alpha compatibility aliases; new components should use --fray-* names. */
+  --base-font-size: var(--fray-font-size);
+  --ui-font-size: var(--fray-font-size);
+  --ui-padding: var(--fray-space-sm);
+  --ui-padding-h: var(--fray-space-sm);
+  --ui-padding-v: var(--fray-space-xs);
+  --ui-border-radius: var(--fray-radius-md);
+  --ui-text-color: var(--fray-ui-color);
+  --ui-muted-text-color: var(--fray-color-text-muted);
+  --ui-border-color: var(--fray-color-border);
+  --ui-input-bg: var(--fray-input-background);
+  --ui-input-border: var(--fray-input-border);
+  --ui-input-bg-disabled: var(--fray-input-background-disabled);
+  --ui-input-border-disabled: 1px solid var(--fray-color-border);
+  --ui-input-text-color-disabled: var(--fray-input-color-disabled);
+  --ui-accent-color: var(--fray-color-primary);
+  --ui-accent-color-highlight: var(--fray-color-primary-soft);
+  --input-width: 15rem;
+  --input-shadow: var(--fray-input-shadow);
+  --button-background: var(--fray-button-background);
+  --button-background-hover: var(--fray-button-background-hover);
+  --button-background-disabled: var(--fray-button-background-disabled);
+  --button-border: var(--fray-button-border);
+  --button-border-disabled: 1px solid var(--fray-color-border);
+  --button-shadow: var(--fray-button-shadow);
+  --button-color: var(--fray-button-color);
+  --toggle-selected-bg: var(--fray-selection-background);
+  --toggle-selected-text: var(--fray-selection-color);
+  --panel-bg: var(--fray-panel-background);
+  --panel-border: var(--fray-panel-border);
+  --panel-radius: var(--fray-panel-radius);
+  --panel-shadow: var(--fray-panel-shadow);
+  --panel-color: var(--fray-panel-color);
+  --panel-padding: var(--fray-space-md);
+  --toolbar-bg: var(--fray-toolbar-background);
+  --toolbar-border: var(--fray-toolbar-border);
+  --toolbar-radius: var(--fray-radius-md);
+  --toolbar-shadow: var(--fray-toolbar-shadow);
+  --toolbar-color: var(--fray-toolbar-color);
+  --sectionheader-bg: var(--fray-section-header-background, var(--fray-header-background));
+  --sectionheader-shadow: var(--fray-header-shadow);
+  --sectionheader-color: var(--fray-header-color);
+  --tabline-bg: var(--fray-tabline-background);
+  --tab-bg-active: var(--fray-tab-active-background);
+  --error-color: var(--fray-color-error);
+  --cbx-o-border: var(--fray-checkbox-box-border);
+  --cbx-border-radius: var(--fray-radius-sm);
+  --spacing-small: var(--fray-space-sm);
+  --spacing-medium: var(--fray-space-md);
+  --noselect-user-select: none;
+  --noselect-cursor: default;
+}