soltana-ui 0.1.0

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 (104) hide show
  1. package/README.md +158 -0
  2. package/dist/config/index.d.ts +3 -0
  3. package/dist/config/index.js +7 -0
  4. package/dist/config/register.d.ts +27 -0
  5. package/dist/config/stylesheet.d.ts +13 -0
  6. package/dist/config/types.d.ts +177 -0
  7. package/dist/config/types.js +7 -0
  8. package/dist/config/validation.d.ts +29 -0
  9. package/dist/config/validation.js +59 -0
  10. package/dist/enhancers/accordion.d.ts +19 -0
  11. package/dist/enhancers/carousel.d.ts +21 -0
  12. package/dist/enhancers/collapsible.d.ts +14 -0
  13. package/dist/enhancers/color-picker.d.ts +20 -0
  14. package/dist/enhancers/combobox.d.ts +17 -0
  15. package/dist/enhancers/context-menu.d.ts +19 -0
  16. package/dist/enhancers/date-picker.d.ts +8 -0
  17. package/dist/enhancers/drawer.d.ts +11 -0
  18. package/dist/enhancers/dropdown.d.ts +17 -0
  19. package/dist/enhancers/hover-card.d.ts +15 -0
  20. package/dist/enhancers/index.d.ts +42 -0
  21. package/dist/enhancers/modal.d.ts +16 -0
  22. package/dist/enhancers/scroll-area.d.ts +14 -0
  23. package/dist/enhancers/tabs.d.ts +26 -0
  24. package/dist/enhancers/test-helpers.d.ts +20 -0
  25. package/dist/enhancers/test-utils.d.ts +10 -0
  26. package/dist/enhancers/toast.d.ts +24 -0
  27. package/dist/enhancers/tooltip.d.ts +15 -0
  28. package/dist/enhancers/tree.d.ts +24 -0
  29. package/dist/enhancers/utils/click-away.d.ts +7 -0
  30. package/dist/enhancers/utils/create-overlay-enhancer.d.ts +14 -0
  31. package/dist/enhancers/utils/focus-trap.d.ts +9 -0
  32. package/dist/enhancers/utils/generate-id.d.ts +6 -0
  33. package/dist/enhancers/utils/keyboard-nav.d.ts +21 -0
  34. package/dist/enhancers/utils/position.d.ts +30 -0
  35. package/dist/fonts/index.d.ts +20 -0
  36. package/dist/index.d.ts +9 -0
  37. package/dist/init.d.ts +16 -0
  38. package/dist/plugins/index.d.ts +2 -0
  39. package/dist/plugins/index.js +1 -0
  40. package/dist/plugins/postcss-soltana-treeshake.d.ts +10 -0
  41. package/dist/plugins/postcss-soltana-treeshake.js +149 -0
  42. package/dist/plugins/types.d.ts +9 -0
  43. package/dist/plugins/types.js +4 -0
  44. package/dist/soltana-ui.css +1 -0
  45. package/dist/soltana-ui.js +1702 -0
  46. package/dist/soltana-ui.umd.cjs +1 -0
  47. package/package.json +90 -0
  48. package/src/styles/_variables.scss +348 -0
  49. package/src/styles/base/_accessibility.scss +146 -0
  50. package/src/styles/base/_index.scss +12 -0
  51. package/src/styles/base/_register.scss +84 -0
  52. package/src/styles/base/_relief-system.scss +53 -0
  53. package/src/styles/base/_scrollbar.scss +40 -0
  54. package/src/styles/base/_transitions.scss +75 -0
  55. package/src/styles/base/_typography.scss +442 -0
  56. package/src/styles/components/_alert-dialogs.scss +75 -0
  57. package/src/styles/components/_badges.scss +215 -0
  58. package/src/styles/components/_buttons.scss +293 -0
  59. package/src/styles/components/_callouts.scss +99 -0
  60. package/src/styles/components/_cards.scss +97 -0
  61. package/src/styles/components/_carousels.scss +108 -0
  62. package/src/styles/components/_closes.scss +63 -0
  63. package/src/styles/components/_code.scss +75 -0
  64. package/src/styles/components/_collapsibles.scss +61 -0
  65. package/src/styles/components/_color-pickers.scss +211 -0
  66. package/src/styles/components/_comboboxes.scss +88 -0
  67. package/src/styles/components/_context-menus.scss +82 -0
  68. package/src/styles/components/_date-pickers.scss +165 -0
  69. package/src/styles/components/_feedback.scss +354 -0
  70. package/src/styles/components/_figures.scss +52 -0
  71. package/src/styles/components/_heros.scss +83 -0
  72. package/src/styles/components/_hover-cards.scss +55 -0
  73. package/src/styles/components/_images.scss +71 -0
  74. package/src/styles/components/_index.scss +41 -0
  75. package/src/styles/components/_indicators.scss +403 -0
  76. package/src/styles/components/_inputs.scss +409 -0
  77. package/src/styles/components/_layouts.scss +139 -0
  78. package/src/styles/components/_lists.scss +135 -0
  79. package/src/styles/components/_menus.scss +195 -0
  80. package/src/styles/components/_navigation.scss +325 -0
  81. package/src/styles/components/_overlays.scss +233 -0
  82. package/src/styles/components/_scroll-areas.scss +53 -0
  83. package/src/styles/components/_segmented-controls.scss +75 -0
  84. package/src/styles/components/_tables.scss +137 -0
  85. package/src/styles/components/_toasts.scss +111 -0
  86. package/src/styles/components/_toggles.scss +57 -0
  87. package/src/styles/components/_trees.scss +123 -0
  88. package/src/styles/decorative/_classical.scss +196 -0
  89. package/src/styles/decorative/_index.scss +7 -0
  90. package/src/styles/finishes/_index.scss +55 -0
  91. package/src/styles/index.scss +30 -0
  92. package/src/styles/reliefs/_index.scss +66 -0
  93. package/src/styles/reliefs/_neumorphic-tables.scss +92 -0
  94. package/src/styles/themes/_dark.scss +130 -0
  95. package/src/styles/themes/_index.scss +3 -0
  96. package/src/styles/themes/_light.scss +122 -0
  97. package/src/styles/themes/_sepia.scss +121 -0
  98. package/src/styles/utilities/_index.scss +13 -0
  99. package/src/styles/utilities/_layout.scss +100 -0
  100. package/src/styles/utilities/_mixins.scss +410 -0
  101. package/src/styles/utilities/_responsive.scss +46 -0
  102. package/src/styles/utilities/_sizing.scss +62 -0
  103. package/src/styles/utilities/_spacing.scss +12 -0
  104. package/src/styles/utilities/_visual.scss +436 -0
package/README.md ADDED
@@ -0,0 +1,158 @@
1
+ <div align="center">
2
+
3
+ # soltana-ui
4
+
5
+ [![npm version](https://img.shields.io/npm/v/soltana-ui?color=ff79c6&logo=npm&logoColor=white&labelColor=6272a4)](https://www.npmjs.com/package/soltana-ui)
6
+ [![License: MIT](https://img.shields.io/badge/License-MIT-8be9fd?logo=opensourceinitiative&logoColor=white&labelColor=6272a4)](LICENSE)
7
+ [![TypeScript](https://img.shields.io/badge/TypeScript-5.9+-bd93f9?logo=typescript&logoColor=white&labelColor=6272a4)](https://www.typescriptlang.org/)
8
+
9
+ ---
10
+
11
+ CSS-first design system with a 3-tier orthogonal configuration model:
12
+ **Theme** × **Relief** × **Finish**.
13
+
14
+ [Documentation](https://soltana-tech.github.io/soltana-ui/) •
15
+ [Component Gallery](https://soltana-tech.github.io/soltana-ui/#/explore) •
16
+ [Playground](https://soltana-tech.github.io/soltana-ui/#/playground)
17
+
18
+ ---
19
+
20
+ </div>
21
+
22
+ ## Features
23
+
24
+ - **3-tier orthogonal architecture** — Compose theme (color), relief
25
+ (shadow model), and finish (surface treatment) independently
26
+ - **Per-element composition** — Apply tier configurations globally or
27
+ per-element via utility classes
28
+ - **Runtime registration** — Register custom themes, reliefs, and finishes
29
+ at runtime
30
+ - **16 accessible enhancers** — Modals, tabs, tooltips, accordions,
31
+ carousels, color pickers, date pickers, and more
32
+ - **CSS-first philosophy** — All rendering stays in CSS; JS only handles
33
+ behavior and injects runtime-computed values
34
+
35
+ ## Installation
36
+
37
+ ```bash
38
+ npm install soltana-ui
39
+ ```
40
+
41
+ ## Quick Start
42
+
43
+ ### HTML + CDN
44
+
45
+ ```html
46
+ <!DOCTYPE html>
47
+ <html data-theme="dark" data-relief="glassmorphic" data-finish="frosted">
48
+ <head>
49
+ <link rel="stylesheet" href="https://unpkg.com/soltana-ui/dist/soltana-ui.css" />
50
+ </head>
51
+ <body>
52
+ <button class="btn btn-primary">Hello Soltana</button>
53
+ <script type="module">
54
+ import { loadSoltanaFonts } from 'https://unpkg.com/soltana-ui';
55
+ loadSoltanaFonts();
56
+ </script>
57
+ </body>
58
+ </html>
59
+ ```
60
+
61
+ ### Import CSS + JS
62
+
63
+ ```typescript
64
+ import 'soltana-ui/css';
65
+ import { loadSoltanaFonts, initModals, initTooltips } from 'soltana-ui';
66
+
67
+ loadSoltanaFonts();
68
+ initModals();
69
+ initTooltips();
70
+ ```
71
+
72
+ ### Using SCSS Source
73
+
74
+ ```scss
75
+ @use 'soltana-ui/scss' as soltana;
76
+ ```
77
+
78
+ ## The 3-Tier Model
79
+
80
+ | Tier | Options | Global Activation | Per-Element Class |
81
+ | ---------- | ---------------------------------------------------- | ----------------------------------- | ---------------------- |
82
+ | **Theme** | `dark`, `light`, `sepia`, `auto` | `<html data-theme="dark">` | `.theme-dark` |
83
+ | **Relief** | `flat`, `glassmorphic`, `skeuomorphic`, `neumorphic` | `<html data-relief="glassmorphic">` | `.relief-glassmorphic` |
84
+ | **Finish** | `matte`, `frosted`, `tinted`, `glossy` | `<html data-finish="frosted">` | `.finish-frosted` |
85
+
86
+ ```html
87
+ <!-- Global tier activation -->
88
+ <html data-theme="dark" data-relief="neumorphic" data-finish="matte">
89
+ <!-- Per-element tier override -->
90
+ <div class="card theme-light relief-flat finish-glossy">Mixed tier configuration</div>
91
+ </html>
92
+ ```
93
+
94
+ ## Runtime Registration
95
+
96
+ ```typescript
97
+ import { registerTheme, registerRelief, registerFinish } from 'soltana-ui';
98
+
99
+ // Register a custom theme from seed colors
100
+ registerTheme({
101
+ name: 'ocean',
102
+ seedColors: {
103
+ primary: '#0ea5e9',
104
+ secondary: '#06b6d4',
105
+ accent: '#3b82f6',
106
+ },
107
+ });
108
+
109
+ // Register a custom relief
110
+ registerRelief({
111
+ name: 'lifted',
112
+ tokens: {
113
+ '--shadow-near': '0 4px 8px rgba(0,0,0,0.2)',
114
+ '--shadow-far': '0 12px 24px rgba(0,0,0,0.3)',
115
+ },
116
+ });
117
+ ```
118
+
119
+ ## PostCSS Tree-Shaking
120
+
121
+ Remove unused tier CSS in production:
122
+
123
+ ```javascript
124
+ // postcss.config.mjs
125
+ import soltanaTreeshake from 'soltana-ui/postcss';
126
+
127
+ export default {
128
+ plugins: [
129
+ soltanaTreeshake({
130
+ keep: ['dark', 'light', 'glassmorphic', 'neumorphic', 'frosted', 'matte'],
131
+ }),
132
+ ],
133
+ };
134
+ ```
135
+
136
+ ## Ecosystem
137
+
138
+ | Package | Purpose |
139
+ | ----------------------------------- | -------------------------------------------------------------- |
140
+ | [`@soltana-ui/tokens`](../tokens) | Token compiler — outputs Mermaid themes, DTCG JSON, agent docs |
141
+ | [`@soltana-ui/react`](../react) | React bindings — `useSoltana()` hook, `SoltanaProvider` |
142
+ | [`@soltana-ui/mermaid`](../mermaid) | Mermaid theme bridge for diagram synchronization |
143
+
144
+ ## Documentation
145
+
146
+ - **[Full Documentation](https://soltana-tech.github.io/soltana-ui/)**
147
+ - **[Component Gallery](https://soltana-tech.github.io/soltana-ui/#/explore)**
148
+ — Live interactive previews of all components
149
+ - **[Playground](https://soltana-tech.github.io/soltana-ui/#/playground)** —
150
+ Experiment with tier combinations
151
+ - **[Component Reference](https://soltana-tech.github.io/soltana-ui/#/reference/components)**
152
+ — CSS class reference for all components
153
+ - **[AI Agent Reference](https://soltana-tech.github.io/soltana-ui/llms-full.txt)**
154
+ — Machine-readable reference for AI agents
155
+
156
+ ## License
157
+
158
+ MIT License - see [LICENSE](../../LICENSE) file for details.
package/dist/config/index.d.ts ADDED
@@ -0,0 +1,3 @@
1
+ export { VALID_THEMES, VALID_RELIEFS, VALID_FINISHES } from './validation.js';
2
+ export { BUILT_IN_THEMES, BUILT_IN_RELIEFS, BUILT_IN_FINISHES } from './types.js';
3
+ export type { SoltanaConfig, SoltanaInitOptions, SoltanaInstance, SoltanaChangeDetail, EnhancerCleanup, EnhancerOptions, Theme, Relief, Finish, BuiltInTheme, BuiltInRelief, BuiltInFinish, TierName, SoltanaChangeType, ThemeSeed, RegisterThemeOptions, RegisterReliefOptions, RegisterFinishOptions, TierRegistration, } from './types.js';
package/dist/config/index.js ADDED
@@ -0,0 +1,7 @@
1
+ // ---------------------------------------------------------------------------
2
+ // Config Barrel
3
+ // ---------------------------------------------------------------------------
4
+ // Pure data, types, and validation. Orchestration lives in src/init.ts.
5
+ // ---------------------------------------------------------------------------
6
+ export { VALID_THEMES, VALID_RELIEFS, VALID_FINISHES } from './validation.js';
7
+ export { BUILT_IN_THEMES, BUILT_IN_RELIEFS, BUILT_IN_FINISHES } from './types.js';
package/dist/config/register.d.ts ADDED
@@ -0,0 +1,27 @@
1
+ import { ThemeSeed, RegisterThemeOptions, RegisterReliefOptions, RegisterFinishOptions, TierRegistration } from './types.js';
2
+ /**
3
+ * All CSS custom properties a theme rule block defines. Source of truth for
4
+ * the runtime derivation function and the SCSS ↔ TS sync test.
5
+ * Icon tokens are included in the schema but not derived — icon tokens require
6
+ * compile-time SVG template functions and must be provided via `tokens`
7
+ * overrides if needed.
8
+ *
9
+ * @internal Consumed only by tests; not re-exported from the public barrel.
10
+ */
11
+ export declare const THEME_TOKEN_NAMES: readonly ["--surface-bg", "--surface-1", "--surface-2", "--surface-3", "--surface-4", "--text-primary", "--text-secondary", "--text-tertiary", "--text-muted", "--text-inverse", "--border-default", "--border-subtle", "--border-strong", "--accent-primary", "--accent-primary-hover", "--accent-primary-active", "--accent-secondary", "--accent-secondary-hover", "--accent-secondary-active", "--accent-decorative", "--accent-decorative-hover", "--accent-decorative-subtle", "--border-decorative", "--border-decorative-strong", "--color-success", "--color-success-subtle", "--color-success-text", "--color-warning", "--color-warning-subtle", "--color-warning-text", "--color-error", "--color-error-subtle", "--color-error-text", "--color-info", "--color-info-subtle", "--color-info-text", "--state-hover", "--state-active", "--state-focus-ring", "--state-disabled-bg", "--state-disabled-text", "--shadow-color", "--highlight-color", "--accent-glow", "--channel-sheen-color", "--channel-tint-color", "--glass-opacity", "--mesh-color-1", "--mesh-color-2", "--mesh-color-3", "--surface-deep", "--neu-shadow", "--neu-light", "--input-bg", "--input-border", "--input-border-focus", "--input-placeholder", "--card-bg", "--card-border", "--badge-bg", "--tooltip-bg", "--tooltip-text", "--scrollbar-thumb", "--scrollbar-track", "--code-bg", "--toast-bg", "--toast-text", "--drawer-bg", "--popover-bg", "--popover-border", "--kbd-bg", "--kbd-border", "--modal-bg", "--overlay-backdrop-bg", "--icon-select-chevron"];
12
+ /**
13
+ * Derive a full theme token map from a ThemeSeed (3 required + up to 7 optional color fields).
14
+ *
15
+ * Pure function with no DOM dependency. Token values use CSS `color-mix()`
16
+ * expressions that the browser evaluates at paint time, keeping derived
17
+ * tokens reactive.
18
+ *
19
+ * Icon tokens (`--icon-*`) are not derived; provide icon values via the
20
+ * `tokens` override map in `RegisterThemeOptions` if needed.
21
+ *
22
+ * @internal Consumed by `registerTheme()` and tests; not re-exported from the public barrel.
23
+ */
24
+ export declare function deriveThemeTokens(seed: ThemeSeed): Record<string, string>;
25
+ export declare function registerTheme(name: string, options: RegisterThemeOptions): TierRegistration;
26
+ export declare function registerRelief(name: string, options: RegisterReliefOptions): TierRegistration;
27
+ export declare function registerFinish(name: string, options: RegisterFinishOptions): TierRegistration;
package/dist/config/stylesheet.d.ts ADDED
@@ -0,0 +1,13 @@
1
+ /**
2
+ * Append a CSS rule and return the inserted CSSRule reference.
3
+ * Using references (not indices) avoids stale-index problems when
4
+ * earlier registrations are unregistered.
5
+ */
6
+ export declare function insertRule(cssText: string): CSSRule;
7
+ /**
8
+ * Remove rules by reference. Finds current indices and deletes in
9
+ * reverse order so earlier deletions don't shift later indices.
10
+ */
11
+ export declare function removeRules(rules: CSSRule[]): void;
12
+ /** Remove the stylesheet from the document entirely. */
13
+ export declare function teardown(): void;
package/dist/config/types.d.ts ADDED
@@ -0,0 +1,177 @@
1
+ export declare const BUILT_IN_THEMES: readonly ["dark", "light", "sepia"];
2
+ export declare const BUILT_IN_RELIEFS: readonly ["flat", "glassmorphic", "skeuomorphic", "neumorphic"];
3
+ export declare const BUILT_IN_FINISHES: readonly ["matte", "frosted", "tinted", "glossy"];
4
+ export type BuiltInTheme = (typeof BUILT_IN_THEMES)[number];
5
+ export type BuiltInRelief = (typeof BUILT_IN_RELIEFS)[number];
6
+ export type BuiltInFinish = (typeof BUILT_IN_FINISHES)[number];
7
+ export type Theme = BuiltInTheme | 'auto' | (string & {});
8
+ export type Relief = BuiltInRelief | (string & {});
9
+ export type Finish = BuiltInFinish | (string & {});
10
+ /**
11
+ * Initialization-only options consumed by `initSoltana()`.
12
+ *
13
+ * These are merged with `SoltanaConfig` in the `initSoltana()` parameter via a
14
+ * flattened union (`Partial<SoltanaConfig & SoltanaInitOptions>`) so callers
15
+ * pass a single options object rather than nested config + init groups.
16
+ */
17
+ export interface SoltanaInitOptions {
18
+ /** Enable progressive-enhancement enhancers for all component types. */
19
+ enhancers?: boolean;
20
+ /**
21
+ * Enables strict validation — throws errors instead of logging warnings for invalid tier values.
22
+ * Intended for development and testing environments.
23
+ */
24
+ strict?: boolean;
25
+ }
26
+ export interface SoltanaConfig {
27
+ theme: Theme;
28
+ relief: Relief;
29
+ finish: Finish;
30
+ overrides: Record<string, string>;
31
+ }
32
+ /**
33
+ * Public API surface returned by `initSoltana()`.
34
+ *
35
+ * All members are part of the public API and may be destructured from the
36
+ * returned instance.
37
+ */
38
+ export interface SoltanaInstance {
39
+ /** Return a snapshot of the current tier configuration. */
40
+ getState(): SoltanaConfig;
41
+ /** Set the active theme (applies `data-theme` on `<html>`). */
42
+ setTheme(theme: Theme): void;
43
+ /** Set the active relief (applies `data-relief` on `<html>`). */
44
+ setRelief(relief: Relief): void;
45
+ /** Set the active finish (applies `data-finish` on `<html>`). */
46
+ setFinish(finish: Finish): void;
47
+ /** Set CSS custom property overrides on `<html>`. Keys must start with `--`. */
48
+ setOverrides(overrides: Record<string, string>): void;
49
+ /** Remove previously set CSS custom property overrides. Keys must start with `--`. */
50
+ removeOverrides(keys: string[]): void;
51
+ /** Register a custom theme by deriving tokens from a seed. */
52
+ registerTheme(name: string, options: RegisterThemeOptions): TierRegistration;
53
+ /** Register a custom relief with a typed token map. */
54
+ registerRelief(name: string, options: RegisterReliefOptions): TierRegistration;
55
+ /** Register a custom finish with a typed token map. */
56
+ registerFinish(name: string, options: RegisterFinishOptions): TierRegistration;
57
+ /**
58
+ * Destroy and re-create all enhancer types.
59
+ * No-op when `enhancers: false` (the default) was passed to `initSoltana()`.
60
+ */
61
+ reinitEnhancers(): void;
62
+ /** Reset all tiers to defaults and remove overrides and registrations. */
63
+ reset(): void;
64
+ /** Tear down the instance: remove all attributes, listeners, and registrations. */
65
+ destroy(): void;
66
+ }
67
+ export interface EnhancerCleanup {
68
+ destroy(): void;
69
+ }
70
+ /**
71
+ * Enhancer initialization options.
72
+ */
73
+ export interface EnhancerOptions {
74
+ /**
75
+ * Root element to scope queries. Defaults to `document`.
76
+ */
77
+ root?: Element | Document;
78
+ /**
79
+ * Override the default component selector for this enhancer. Allows targeting custom element
80
+ * selectors instead of the built-in `[data-sol-*]` attributes.
81
+ */
82
+ selector?: string;
83
+ }
84
+ export type TierName = 'theme' | 'relief' | 'finish';
85
+ export type SoltanaChangeType = 'theme' | 'relief' | 'finish' | 'overrides' | 'reset' | 'destroy';
86
+ /** Detail payload for `soltana:change` custom events. */
87
+ export interface SoltanaChangeDetail {
88
+ type: SoltanaChangeType;
89
+ value: unknown;
90
+ }
91
+ /**
92
+ * Seed colors used to derive a full theme token palette via `registerTheme()`.
93
+ *
94
+ * Only the three required fields (`surfaceBg`, `textPrimary`, `accentPrimary`)
95
+ * are needed to generate a complete token set. Optional fields fall back to
96
+ * curated defaults selected for the chosen `colorScheme` — dark-scheme
97
+ * defaults use lighter, higher-contrast values while light-scheme defaults
98
+ * use darker, lower-saturation values.
99
+ */
100
+ export interface ThemeSeed {
101
+ /** Base surface/background color for the theme. */
102
+ surfaceBg: string;
103
+ /** Primary text color. */
104
+ textPrimary: string;
105
+ /**
106
+ * Primary accent / brand color.
107
+ */
108
+ accentPrimary: string;
109
+ /**
110
+ * Advanced overrides for semantic color control. For fine-grained per-token
111
+ * customization, use the `tokens` map in RegisterThemeOptions instead.
112
+ */
113
+ /**
114
+ * Decorative accent for borders and highlights. Defaults to `accentPrimary`.
115
+ * @remarks Advanced
116
+ */
117
+ accentDecorative?: string;
118
+ /** Light or dark scheme hint for derived token generation. Defaults to `'dark'`. */
119
+ colorScheme?: 'light' | 'dark';
120
+ /**
121
+ * Semantic success color. Defaults to green (#10b981 dark / #0d6b4e light).
122
+ * @remarks Advanced
123
+ */
124
+ colorSuccess?: string;
125
+ /**
126
+ * Semantic warning color. Defaults to amber (#fcd34d dark / #855c0a light).
127
+ * @remarks Advanced
128
+ */
129
+ colorWarning?: string;
130
+ /**
131
+ * Semantic error color. Defaults to red (#ef4444 dark / #991b1b light).
132
+ * @remarks Advanced
133
+ */
134
+ colorError?: string;
135
+ /**
136
+ * Semantic info color. Defaults to blue (#3b82f6 dark / #1e40af light).
137
+ * @remarks Advanced
138
+ */
139
+ colorInfo?: string;
140
+ /**
141
+ * Highlight channel (R G B space-separated). Defaults to '255 255 255'.
142
+ * @remarks Advanced
143
+ */
144
+ highlightColor?: string;
145
+ }
146
+ export interface RegisterThemeOptions {
147
+ seed: ThemeSeed;
148
+ /** Override any derived token after seed derivation. */
149
+ tokens?: Record<string, string>;
150
+ }
151
+ export interface RegisterReliefOptions {
152
+ tokens: {
153
+ '--relief-bg': string;
154
+ '--relief-shadow-sm': string;
155
+ '--relief-shadow': string;
156
+ '--relief-shadow-lg': string;
157
+ '--relief-shadow-inset-sm': string;
158
+ '--relief-shadow-inset': string;
159
+ '--relief-shadow-inset-lg': string;
160
+ '--relief-border': string;
161
+ '--relief-opacity'?: string;
162
+ };
163
+ }
164
+ export interface RegisterFinishOptions {
165
+ tokens: {
166
+ '--finish-blur': string;
167
+ '--finish-saturation': string;
168
+ '--finish-opacity': string;
169
+ '--finish-overlay': string;
170
+ '--finish-sheen': string;
171
+ };
172
+ }
173
+ export interface TierRegistration {
174
+ readonly name: string;
175
+ readonly tier: TierName;
176
+ unregister(): void;
177
+ }
package/dist/config/types.js ADDED
@@ -0,0 +1,7 @@
1
+ // ---------------------------------------------------------------------------
2
+ // Soltana Config Types
3
+ // ---------------------------------------------------------------------------
4
+ // Canonical built-in tier values (CSS-emitted values only; 'auto' is runtime)
5
+ export const BUILT_IN_THEMES = ['dark', 'light', 'sepia'];
6
+ export const BUILT_IN_RELIEFS = ['flat', 'glassmorphic', 'skeuomorphic', 'neumorphic'];
7
+ export const BUILT_IN_FINISHES = ['matte', 'frosted', 'tinted', 'glossy'];
package/dist/config/validation.d.ts ADDED
@@ -0,0 +1,29 @@
1
+ import type { TierName } from './types.js';
2
+ /**
3
+ * Register a custom tier value so `strict` mode does not warn for it.
4
+ * Call before `initSoltana()` or at any point before the value is used.
5
+ */
6
+ export declare function registerTierValue(tier: TierName, value: string): void;
7
+ /**
8
+ * Remove a custom tier value from the registry (e.g. on unregister).
9
+ */
10
+ export declare function deregisterTierValue(tier: TierName, value: string): void;
11
+ /**
12
+ * Live registry of valid theme values. Includes built-in themes, `'auto'`
13
+ * (runtime resolver — not a static token set), and any values added at
14
+ * runtime via `registerTierValue()` or `registerTheme()`.
15
+ *
16
+ * Note: `BUILT_IN_THEMES` (from types.ts) excludes `'auto'` since it has
17
+ * no corresponding CSS ruleset.
18
+ */
19
+ export declare const VALID_THEMES: readonly string[];
20
+ /**
21
+ * Live registry of valid relief values. Includes built-in reliefs and any
22
+ * values added at runtime via `registerTierValue()` or `registerRelief()`.
23
+ */
24
+ export declare const VALID_RELIEFS: readonly string[];
25
+ /**
26
+ * Live registry of valid finish values. Includes built-in finishes and any
27
+ * values added at runtime via `registerTierValue()` or `registerFinish()`.
28
+ */
29
+ export declare const VALID_FINISHES: readonly string[];
package/dist/config/validation.js ADDED
@@ -0,0 +1,59 @@
1
+ // ---------------------------------------------------------------------------
2
+ // Tier Validation Registry
3
+ // ---------------------------------------------------------------------------
4
+ // Shared validation state for tier values. Extracted to its own module so
5
+ // both config/index.ts and config/register.ts can import without a cycle.
6
+ // ---------------------------------------------------------------------------
7
+ import { BUILT_IN_THEMES, BUILT_IN_RELIEFS, BUILT_IN_FINISHES } from './types.js';
8
+ // Backing arrays are mutable so registerTierValue/deregisterTierValue can
9
+ // modify values at runtime. The exported VALID_* constants are live views into
10
+ // these arrays — array contents update automatically when runtime tier
11
+ // registration occurs. The constants are typed as readonly to discourage direct
12
+ // mutation by consumers.
13
+ const _themes = [...BUILT_IN_THEMES, 'auto'];
14
+ const _reliefs = [...BUILT_IN_RELIEFS];
15
+ const _finishes = [...BUILT_IN_FINISHES];
16
+ const TIER_REGISTRY = {
17
+ theme: _themes,
18
+ relief: _reliefs,
19
+ finish: _finishes,
20
+ };
21
+ /**
22
+ * Register a custom tier value so `strict` mode does not warn for it.
23
+ * Call before `initSoltana()` or at any point before the value is used.
24
+ */
25
+ export function registerTierValue(tier, value) {
26
+ const arr = TIER_REGISTRY[tier];
27
+ if (!arr.includes(value)) {
28
+ arr.push(value);
29
+ }
30
+ }
31
+ /**
32
+ * Remove a custom tier value from the registry (e.g. on unregister).
33
+ */
34
+ export function deregisterTierValue(tier, value) {
35
+ const arr = TIER_REGISTRY[tier];
36
+ const index = arr.indexOf(value);
37
+ if (index !== -1) {
38
+ arr.splice(index, 1);
39
+ }
40
+ }
41
+ /**
42
+ * Live registry of valid theme values. Includes built-in themes, `'auto'`
43
+ * (runtime resolver — not a static token set), and any values added at
44
+ * runtime via `registerTierValue()` or `registerTheme()`.
45
+ *
46
+ * Note: `BUILT_IN_THEMES` (from types.ts) excludes `'auto'` since it has
47
+ * no corresponding CSS ruleset.
48
+ */
49
+ export const VALID_THEMES = _themes;
50
+ /**
51
+ * Live registry of valid relief values. Includes built-in reliefs and any
52
+ * values added at runtime via `registerTierValue()` or `registerRelief()`.
53
+ */
54
+ export const VALID_RELIEFS = _reliefs;
55
+ /**
56
+ * Live registry of valid finish values. Includes built-in finishes and any
57
+ * values added at runtime via `registerTierValue()` or `registerFinish()`.
58
+ */
59
+ export const VALID_FINISHES = _finishes;
package/dist/enhancers/accordion.d.ts ADDED
@@ -0,0 +1,19 @@
1
+ import { EnhancerCleanup, EnhancerOptions } from '../config/types.js';
2
+ export declare const ACCORDION_SELECTOR = "[data-sol-accordion]";
3
+ /**
4
+ * Enhance all `[data-sol-accordion]` elements with expand/collapse behavior,
5
+ * keyboard navigation, and ARIA attributes.
6
+ *
7
+ * Expected structure:
8
+ * ```html
9
+ * <div data-sol-accordion>
10
+ * <div class="accordion-item active">
11
+ * <div class="accordion-header">Title</div>
12
+ * <div class="accordion-body">Content</div>
13
+ * </div>
14
+ * </div>
15
+ * ```
16
+ *
17
+ * Add `data-accordion-exclusive` for single-open mode.
18
+ */
19
+ export declare function initAccordions(options?: EnhancerOptions): EnhancerCleanup;
package/dist/enhancers/carousel.d.ts ADDED
@@ -0,0 +1,21 @@
1
+ import { EnhancerCleanup, EnhancerOptions } from '../config/types.js';
2
+ export declare const CAROUSEL_SELECTOR = "[data-sol-carousel]";
3
+ /**
4
+ * Enhance all `[data-sol-carousel]` elements with slide navigation,
5
+ * keyboard controls, autoplay, and indicator dots.
6
+ *
7
+ * Expected structure:
8
+ * ```html
9
+ * <div data-sol-carousel class="carousel"
10
+ * data-carousel-autoplay data-carousel-interval="5000" data-carousel-loop>
11
+ * <div class="carousel-track">
12
+ * <div class="carousel-slide">Slide 1</div>
13
+ * <div class="carousel-slide">Slide 2</div>
14
+ * </div>
15
+ * <button class="carousel-prev" aria-label="Previous slide">&lsaquo;</button>
16
+ * <button class="carousel-next" aria-label="Next slide">&rsaquo;</button>
17
+ * <div class="carousel-dots"></div>
18
+ * </div>
19
+ * ```
20
+ */
21
+ export declare function initCarousels(options?: EnhancerOptions): EnhancerCleanup;
package/dist/enhancers/collapsible.d.ts ADDED
@@ -0,0 +1,14 @@
1
+ import { EnhancerCleanup, EnhancerOptions } from '../config/types.js';
2
+ export declare const COLLAPSIBLE_SELECTOR = "[data-sol-collapsible]";
3
+ /**
4
+ * Enhance all `[data-sol-collapsible]` elements with expand/collapse behavior.
5
+ *
6
+ * Expected structure:
7
+ * ```html
8
+ * <div data-sol-collapsible class="collapsible">
9
+ * <button class="collapsible-trigger">Toggle</button>
10
+ * <div class="collapsible-content">Content</div>
11
+ * </div>
12
+ * ```
13
+ */
14
+ export declare function initCollapsibles(options?: EnhancerOptions): EnhancerCleanup;
package/dist/enhancers/color-picker.d.ts ADDED
@@ -0,0 +1,20 @@
1
+ import { EnhancerCleanup, EnhancerOptions } from '../config/types.js';
2
+ export declare const COLOR_PICKER_SELECTOR = "[data-sol-color-picker]";
3
+ /**
4
+ * Enhance all `[data-sol-color-picker]` elements with interactive
5
+ * color selection behavior.
6
+ *
7
+ * Expected structure:
8
+ * ```html
9
+ * <div data-sol-color-picker class="color-picker">
10
+ * <button class="color-picker-trigger" style="background: #d4a843;"></button>
11
+ * <div class="color-picker-popup">
12
+ * <div class="color-picker-area"></div>
13
+ * <div class="color-picker-hue"></div>
14
+ * <input class="color-picker-input input" value="#d4a843" />
15
+ * <div class="color-picker-swatches" data-swatches='["#d4a843","#a855f7"]'></div>
16
+ * </div>
17
+ * </div>
18
+ * ```
19
+ */
20
+ export declare function initColorPickers(options?: EnhancerOptions): EnhancerCleanup;
package/dist/enhancers/combobox.d.ts ADDED
@@ -0,0 +1,17 @@
1
+ import { EnhancerCleanup, EnhancerOptions } from '../config/types.js';
2
+ export declare const COMBOBOX_SELECTOR = "[data-sol-combobox]";
3
+ /**
4
+ * Enhance all `[data-sol-combobox]` elements with filtering, keyboard
5
+ * navigation, and ARIA combobox behavior.
6
+ *
7
+ * Expected structure:
8
+ * ```html
9
+ * <div data-sol-combobox class="combobox">
10
+ * <input class="combobox-input input" role="combobox" />
11
+ * <ul class="combobox-listbox" role="listbox">
12
+ * <li class="combobox-option" role="option">Option 1</li>
13
+ * </ul>
14
+ * </div>
15
+ * ```
16
+ */
17
+ export declare function initComboboxes(options?: EnhancerOptions): EnhancerCleanup;
package/dist/enhancers/context-menu.d.ts ADDED
@@ -0,0 +1,19 @@
1
+ import { EnhancerCleanup, EnhancerOptions } from '../config/types.js';
2
+ export declare const CONTEXT_MENU_SELECTOR = "[data-sol-context-menu]";
3
+ /**
4
+ * Enhance all `[data-sol-context-menu]` elements with right-click
5
+ * triggered floating menu behavior.
6
+ *
7
+ * Expected structure:
8
+ * ```html
9
+ * <div data-sol-context-menu>
10
+ * <div class="context-menu" role="menu">
11
+ * <button class="context-menu-item" role="menuitem">Cut</button>
12
+ * <button class="context-menu-item" role="menuitem">Copy</button>
13
+ * </div>
14
+ * <!-- Trigger area content -->
15
+ * <p>Right-click here</p>
16
+ * </div>
17
+ * ```
18
+ */
19
+ export declare function initContextMenus(options?: EnhancerOptions): EnhancerCleanup;
package/dist/enhancers/date-picker.d.ts ADDED
@@ -0,0 +1,8 @@
1
+ import { EnhancerCleanup, EnhancerOptions } from '../config/types.js';
2
+ export declare const DATE_PICKER_SELECTOR = "[data-sol-date-picker]";
3
+ /**
4
+ * Enhance all `[data-sol-date-picker]` elements with calendar popup behavior.
5
+ *
6
+ * Uses native `<input type="date">` fallback when `data-sol-date-native` is present.
7
+ */
8
+ export declare function initDatePickers(options?: EnhancerOptions): EnhancerCleanup;
package/dist/enhancers/drawer.d.ts ADDED
@@ -0,0 +1,11 @@
1
+ export declare const DRAWER_SELECTOR = "[data-sol-drawer]";
2
+ export declare const DRAWER_OPEN_SELECTOR = "[data-drawer-open]";
3
+ /**
4
+ * Enhance all `[data-sol-drawer]` elements with open/close, focus trapping,
5
+ * Escape key, and backdrop click behavior.
6
+ *
7
+ * Open triggers: `[data-drawer-open="<drawer-id>"]`.
8
+ * Close triggers: `[data-drawer-close]` inside the drawer.
9
+ * Adds `.sol-drawer-open` to `document.body` while any drawer is open.
10
+ */
11
+ export declare const initDrawers: (options?: import('../index.js').EnhancerOptions) => import('../index.js').EnhancerCleanup;
package/dist/enhancers/dropdown.d.ts ADDED
@@ -0,0 +1,17 @@
1
+ import { EnhancerCleanup, EnhancerOptions } from '../config/types.js';
2
+ export declare const DROPDOWN_SELECTOR = "[data-sol-dropdown]";
3
+ /**
4
+ * Enhance all `[data-sol-dropdown]` elements with toggle, click-away,
5
+ * keyboard navigation, and ARIA behavior.
6
+ *
7
+ * Expected structure:
8
+ * ```html
9
+ * <div data-sol-dropdown class="dropdown">
10
+ * <button class="dropdown-toggle">Options</button>
11
+ * <div class="dropdown-menu" role="menu">
12
+ * <button class="dropdown-item" role="menuitem">Edit</button>
13
+ * </div>
14
+ * </div>
15
+ * ```
16
+ */
17
+ export declare function initDropdowns(options?: EnhancerOptions): EnhancerCleanup;