@sheetxl/utils-react 0.8.0-beta.22 → 0.8.0-beta.24
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.
- package/browser/esm/{Hp5-MO2wVxkCzmog.mjs → BHStRhPxBMLg4cBp.mjs} +1 -1
- package/browser/esm/{BoN5GNv_OCJUxgqa.mjs → CbiqCM5Gfw418G85.mjs} +4 -4
- package/browser/esm/{CA9JhaRnLQnZ152c.mjs → DfprIl10b1XU5vUU.mjs} +2 -2
- package/browser/esm/index.mjs +1285 -1345
- package/node/esm/{BuKRRQ8FGiZxTYQ1.mjs → DHdWLQN6GCXXhZ0P.mjs} +1 -1
- package/node/esm/{BQslMd4UYY47M7dX.mjs → DcFUBVRZmI44YcFj.mjs} +1 -1
- package/node/esm/index.mjs +1032 -1092
- package/package.json +2 -2
- package/types/src/float/_FloatTheme.d.ts +2 -3
- package/types/src/hooks/useEditMode.d.ts +2 -2
- package/types/src/scroll/scrollbarTheming.d.ts +2 -23
- package/types/src/theme/TokenTheme.d.ts +2 -1
- package/types/src/theme/buildThemeCSS.d.ts +9 -0
- package/types/src/theme/defaultTheme.d.ts +6 -0
- package/types/src/theme/index.d.ts +1 -1
- package/types/src/theme/tokenVar.d.ts +20 -0
- package/types/src/theme/useResolvedThemeMode.d.ts +6 -2
- package/types/src/theme/TokenThemeProvider.d.ts +0 -97
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@sheetxl/utils-react",
|
|
3
3
|
"description": "Utils React - Utilities for React capabilities needed for all SheetXL components.",
|
|
4
|
-
"version": "0.8.0-beta.
|
|
4
|
+
"version": "0.8.0-beta.24",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"type": "module",
|
|
7
7
|
"exports": {
|
|
@@ -40,7 +40,7 @@
|
|
|
40
40
|
],
|
|
41
41
|
"dependencies": {
|
|
42
42
|
"@floating-ui/react-dom": "^2.1.9",
|
|
43
|
-
"@sheetxl/utils": "^0.8.0-beta.
|
|
43
|
+
"@sheetxl/utils": "^0.8.0-beta.24",
|
|
44
44
|
"clsx": "^2.1.1",
|
|
45
45
|
"detect-it": "^4.0.1",
|
|
46
46
|
"prop-types": "^15.8.1",
|
|
@@ -9,9 +9,8 @@ import { FloatThemeScope } from './FloatUtils';
|
|
|
9
9
|
export declare const useElementThemeAttrs: (el: Element | null) => ThemeAttrs;
|
|
10
10
|
/**
|
|
11
11
|
* The theme an element portaled out of its themed subtree opens with (THEMING-DESIGN §7): the nearest
|
|
12
|
-
* `FloatProvider`'s theme scope,
|
|
13
|
-
*
|
|
14
|
-
* `@scope`d rules apply on the portal root, and its pinned mode is the fallback mode.
|
|
12
|
+
* `FloatProvider`'s theme scope, a React-inherited context that crosses the portal even though the cascade
|
|
13
|
+
* can't.
|
|
15
14
|
*/
|
|
16
15
|
export declare const useFloatThemeScope: () => FloatThemeScope | undefined;
|
|
17
16
|
//# sourceMappingURL=_FloatTheme.d.ts.map
|
|
@@ -7,8 +7,8 @@ import { EditMode, EditModeHandler, SetEditMode } from '@sheetxl/utils';
|
|
|
7
7
|
* @remarks
|
|
8
8
|
* Exists so a non-component owner — e.g. the cell {@link IEditable} publishing its active session —
|
|
9
9
|
* can drive the bus from anywhere, not only where a hook happens to be mounted. Reads (and the React
|
|
10
|
-
* subscription) still go through {@link useEditMode}; this is write-only.
|
|
11
|
-
*
|
|
10
|
+
* subscription) still go through {@link useEditMode}; this is write-only. Before any component has
|
|
11
|
+
* called {@link useEditMode} there is no bus, and the write is dropped.
|
|
12
12
|
*/
|
|
13
13
|
export declare const setEditMode: SetEditMode;
|
|
14
14
|
/** A way out of a mode: {@link EditMode.done} or {@link EditMode.cancel}. */
|
|
@@ -1,27 +1,6 @@
|
|
|
1
1
|
/**
|
|
2
|
-
*
|
|
3
|
-
*
|
|
2
|
+
* Themes the native scrollbars of an element and its descendants from the `--sxl-color-*` tokens, so they
|
|
3
|
+
* match the custom {@link Scrollbar} on the same surface.
|
|
4
4
|
*/
|
|
5
5
|
export declare const scrollbarThemedClassName: string;
|
|
6
|
-
/**
|
|
7
|
-
* Final (already resolved) colors for the scrollbar CSS variables.
|
|
8
|
-
*
|
|
9
|
-
* Color derivation (elevate/alpha) is intentionally left to the caller so this
|
|
10
|
-
* can be overridden.
|
|
11
|
-
*/
|
|
12
|
-
export interface ScrollbarCssVariableColors {
|
|
13
|
-
/** Track background (typically a low-alpha color). */
|
|
14
|
-
track: string;
|
|
15
|
-
thumb: string;
|
|
16
|
-
button?: string;
|
|
17
|
-
active: string;
|
|
18
|
-
corner?: string;
|
|
19
|
-
/** Thumb border color. @defaultValue `track` */
|
|
20
|
-
border?: string;
|
|
21
|
-
}
|
|
22
|
-
/**
|
|
23
|
-
* Maps resolved scrollbar colors to the `--scrollbar-*` CSS variable contract
|
|
24
|
-
* (plus the static size variables). Apply alongside {@link scrollbarThemedClassName}.
|
|
25
|
-
*/
|
|
26
|
-
export declare const getScrollbarCssVariables: (colors: ScrollbarCssVariableColors) => Record<string, string>;
|
|
27
6
|
//# sourceMappingURL=scrollbarTheming.d.ts.map
|
|
@@ -171,6 +171,7 @@ export interface TokenTheme {
|
|
|
171
171
|
'color-neutral'?: string;
|
|
172
172
|
'color-shadow'?: string;
|
|
173
173
|
'color-series'?: string[];
|
|
174
|
+
'color-bracket'?: string[];
|
|
174
175
|
'font-family'?: string;
|
|
175
176
|
/** Monospace stack for code-ish chrome (the formula signature, argument names, evaluated-run tips). */
|
|
176
177
|
'font-family-mono'?: string;
|
|
@@ -194,7 +195,7 @@ export interface TokenTheme {
|
|
|
194
195
|
* read `var(--sxl-image-background)` and it follows the surface.
|
|
195
196
|
*
|
|
196
197
|
* @remarks
|
|
197
|
-
* The sibling `--
|
|
198
|
+
* The sibling `--_sxl-image-filter` (dark-image invert) is deliberately NOT a token: it carries a runtime
|
|
198
199
|
* preference gate (`enableDarkImages`) that a pure mode-driven token can't express — a descendant grid scope
|
|
199
200
|
* would re-emit and un-gate it. It's a single workbook-root computed var instead (see WorkbookElement).
|
|
200
201
|
*/
|
|
@@ -48,6 +48,15 @@ export interface ThemeCSSOptions {
|
|
|
48
48
|
* (the scope root), not `:root`. Omit for a global sheet.
|
|
49
49
|
*/
|
|
50
50
|
scope?: string;
|
|
51
|
+
/**
|
|
52
|
+
* Emit the baseline-only rules: the zero-specificity defaults for elements that carry no theme attribute
|
|
53
|
+
* (the light cell on the root and on each surface), and the generic input text-selection rule. A baseline
|
|
54
|
+
* sheet needs them. An override sheet must not emit them: a later layer beats an earlier one regardless of
|
|
55
|
+
* specificity, so a value stated only for light would also land on dark elements, and the selection rule
|
|
56
|
+
* would outrank a host's own layered styling.
|
|
57
|
+
* @defaultValue true
|
|
58
|
+
*/
|
|
59
|
+
baseline?: boolean;
|
|
51
60
|
}
|
|
52
61
|
/** Build the injectable theme CSS from the app baseline + surface overrides. */
|
|
53
62
|
export declare function buildThemeCSS(options?: ThemeCSSOptions): string;
|
|
@@ -5,6 +5,12 @@ import { TokenTheme, ThemeMode } from './TokenTheme';
|
|
|
5
5
|
* hues (replace the `color-series` array), but never the count. Consumers rotate with `i % SERIES_COUNT`.
|
|
6
6
|
*/
|
|
7
7
|
export declare const SERIES_COUNT = 7;
|
|
8
|
+
/**
|
|
9
|
+
* The length of the `color-bracket` palette (`--sxl-color-bracket-1..N`), the hues matched bracket pairs
|
|
10
|
+
* cycle through by nesting depth. Fixed, like {@link SERIES_COUNT}. Consumers rotate with
|
|
11
|
+
* `depth % BRACKET_COUNT`.
|
|
12
|
+
*/
|
|
13
|
+
export declare const BRACKET_COUNT = 3;
|
|
8
14
|
/**
|
|
9
15
|
* The default theme — the framework-neutral, **unbranded** baseline (per mode) every surface inherits.
|
|
10
16
|
* The floor for an app with no theme at all; a themed app (MUI, VS Code, …) injects its own palette over
|
|
@@ -1,11 +1,11 @@
|
|
|
1
1
|
export * from './TokenTheme';
|
|
2
2
|
export * from './defaultTheme';
|
|
3
3
|
export * from './createThemeVars';
|
|
4
|
+
export * from './tokenVar';
|
|
4
5
|
export * from './buildThemeCSS';
|
|
5
6
|
export * from './themeAttrs';
|
|
6
7
|
export * from './ThemeStyle';
|
|
7
8
|
export * from './zIndex';
|
|
8
|
-
export * from './TokenThemeProvider';
|
|
9
9
|
export * from './useResolvedThemeMode';
|
|
10
10
|
export * from './resolveTokens';
|
|
11
11
|
//# sourceMappingURL=index.d.ts.map
|
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
import { TokenTheme } from './TokenTheme';
|
|
2
|
+
/** The tokens that are a fixed-length list, emitted as numbered vars (`--sxl-color-series-1..N`). */
|
|
3
|
+
type ListToken = 'color-series' | 'color-bracket';
|
|
4
|
+
type ScalarToken = Exclude<keyof TokenTheme, ListToken>;
|
|
5
|
+
/**
|
|
6
|
+
* A CSS `var()` reading a theme token, with the light default as its fallback.
|
|
7
|
+
*
|
|
8
|
+
* Use it wherever a component paints a token in inline styles or SVG attributes. The fallback applies only
|
|
9
|
+
* when no theme stylesheet is in force (a bare grid with no `ThemeRootStyles` above it), and it comes from
|
|
10
|
+
* {@link defaultTheme}, so it cannot drift from the real default.
|
|
11
|
+
*
|
|
12
|
+
* ```ts
|
|
13
|
+
* tokenVar('color-base-300') // 'var(--sxl-color-base-300, #e0e0e0)'
|
|
14
|
+
* tokenVar('color-series', 2) // 'var(--sxl-color-series-3, …)': zero-based, rotates past the end
|
|
15
|
+
* ```
|
|
16
|
+
*/
|
|
17
|
+
export declare function tokenVar(key: ScalarToken): string;
|
|
18
|
+
export declare function tokenVar(key: ListToken, index: number): string;
|
|
19
|
+
export {};
|
|
20
|
+
//# sourceMappingURL=tokenVar.d.ts.map
|
|
@@ -16,8 +16,12 @@ export type ThemeModeFallback = 'system' | ThemeMode;
|
|
|
16
16
|
*/
|
|
17
17
|
export declare const ThemeModeFallbackContext: import('react').Context<ThemeModeFallback>;
|
|
18
18
|
interface UseThemeOptions {
|
|
19
|
-
|
|
20
|
-
|
|
19
|
+
/**
|
|
20
|
+
* An explicit mode. `'auto'` follows the page: a `dark`/`light` class on `<html>`/`<body>`, else the OS
|
|
21
|
+
* (`prefers-color-scheme`), whatever the {@link ThemeModeFallbackContext} says.
|
|
22
|
+
*/
|
|
23
|
+
mode?: ThemeMode | 'auto';
|
|
24
|
+
/** Overrides {@link ThemeModeFallbackContext} for this call. Ignored when `mode` is `'auto'`. */
|
|
21
25
|
fallback?: ThemeModeFallback;
|
|
22
26
|
}
|
|
23
27
|
/**
|
|
@@ -1,97 +0,0 @@
|
|
|
1
|
-
import { default as React } from 'react';
|
|
2
|
-
import { TokenTheme, ThemeMode } from './TokenTheme';
|
|
3
|
-
import { ThemeCSSOptions } from './buildThemeCSS';
|
|
4
|
-
/**
|
|
5
|
-
* What a {@link TokenThemeProvider} publishes to descendants — the *handle*, not resolved values (resolution
|
|
6
|
-
* stays in CSS). A portaled float is a React descendant but NOT a DOM descendant, so the cascade can't reach
|
|
7
|
-
* it; a float layer reads this to re-attach the theme (stamp `scopeClass` + `mode` on its portal root).
|
|
8
|
-
* `light`/`dark` are the already-MERGED inputs so a nested provider can merge further.
|
|
9
|
-
*/
|
|
10
|
-
export interface TokenThemeContextValue {
|
|
11
|
-
/**
|
|
12
|
-
* Per-instance scope class (no leading dot) — present ONLY when the provider is `isolate`d (i.e. it emits
|
|
13
|
-
* `@scope`d rules). A float carries it so those scoped rules apply on the portal root; `undefined` for a
|
|
14
|
-
* global provider (nothing to carry — global rules reach the float anyway).
|
|
15
|
-
*/
|
|
16
|
-
scopeClass?: string;
|
|
17
|
-
/** The mode a float should stamp, when this provider (or an ancestor provider) pins one. */
|
|
18
|
-
mode?: ThemeMode;
|
|
19
|
-
/** Merged light-mode token inputs (base/parent ⊕ own) — a child provider merges on top of these. */
|
|
20
|
-
light?: Partial<TokenTheme>;
|
|
21
|
-
/** Merged dark-mode token inputs. */
|
|
22
|
-
dark?: Partial<TokenTheme>;
|
|
23
|
-
}
|
|
24
|
-
/**
|
|
25
|
-
* The raw context. Exported so a non-`TokenThemeProvider` theme root (e.g. the MUI studio, which builds its
|
|
26
|
-
* own sheet) can still PUBLISH the handle — `<TokenThemeContext.Provider value={{ scopeClass, mode }}>` — so
|
|
27
|
-
* floats and nested `TokenThemeProvider`s see it. Prefer {@link useTokenThemeContext} to read it.
|
|
28
|
-
*/
|
|
29
|
-
export declare const TokenThemeContext: React.Context<TokenThemeContextValue | null>;
|
|
30
|
-
/** Read the nearest {@link TokenThemeProvider}'s handle (scope class + mode + merged inputs), or `null`. */
|
|
31
|
-
export declare const useTokenThemeContext: () => TokenThemeContextValue | null;
|
|
32
|
-
export interface TokenThemeProviderProps {
|
|
33
|
-
/** Light-mode token overrides. Shallow-merged over the base (parent provider ?? `base` prop). Own wins. */
|
|
34
|
-
light?: Partial<TokenTheme>;
|
|
35
|
-
/** Dark-mode token overrides. Shallow-merged over the base. Own wins. */
|
|
36
|
-
dark?: Partial<TokenTheme>;
|
|
37
|
-
/**
|
|
38
|
-
* The app baseline both modes start from, for the **from-scratch** case (theming a bare `Grid`, which has
|
|
39
|
-
* no surfaces of its own). Omit it in the **common** case — wrap a component that already brings its base +
|
|
40
|
-
* surfaces (`Studio`, `WorkbookElement`) and this provider is a pure override layer. Layered low → high as
|
|
41
|
-
* `base` ⊕ parent-provider ⊕ own, so a nested provider keeps `base` as a floor under the inherited tokens.
|
|
42
|
-
*/
|
|
43
|
-
base?: Record<ThemeMode, TokenTheme>;
|
|
44
|
-
/**
|
|
45
|
-
* Named surface overrides (e.g. `{ grid: GRID_SURFACE, header: HEADER_SURFACE }`), passed straight to
|
|
46
|
-
* {@link buildThemeCSS}. Only for the from-scratch case; a wrapped `Studio`/`WorkbookElement` supplies its
|
|
47
|
-
* own. Pass a stable object (it re-emits the sheet when the reference changes).
|
|
48
|
-
*/
|
|
49
|
-
surfaces?: ThemeCSSOptions['surfaces'];
|
|
50
|
-
/**
|
|
51
|
-
* Pin the mode by stamping `data-sxl-theme-mode` on this provider's root (`'auto'` follows the OS / a
|
|
52
|
-
* `light`|`dark` class). **Omit it in the common case** — the wrapped component stamps its own mode, and
|
|
53
|
-
* the mode-keyed overrides follow it via the cascade. Pin it only when the themed content sits on this
|
|
54
|
-
* provider's own root with no inner mode (the from-scratch bare-`Grid` case).
|
|
55
|
-
*/
|
|
56
|
-
mode?: ThemeMode | 'auto';
|
|
57
|
-
/** Stamp `data-sxl-theme-surface` on the root (e.g. `'grid'`). Optional — app is the default surface. */
|
|
58
|
-
surface?: string;
|
|
59
|
-
/**
|
|
60
|
-
* Isolate this instance in an `@scope` so its tokens don't collide with another provider on the page.
|
|
61
|
-
* Default `false` (global) — correct for the common "theme the whole app" case, and it reaches portaled
|
|
62
|
-
* popups for free. Set `true` for multiple independently-themed instances on one page (note: an isolated
|
|
63
|
-
* provider's overrides don't yet reach a WRAPPED component's own portaled floats — that needs float-layer
|
|
64
|
-
* wiring off {@link useTokenThemeContext}). @defaultValue false
|
|
65
|
-
*/
|
|
66
|
-
isolate?: boolean;
|
|
67
|
-
/**
|
|
68
|
-
* The `@layer` the tokens emit into. Default `'sxl-overrides'` — the top layer, so overrides win over the
|
|
69
|
-
* app/defaults regardless of specificity. Pass `'sxl-app'` to act as an app baseline instead.
|
|
70
|
-
* @defaultValue 'sxl-overrides'
|
|
71
|
-
*/
|
|
72
|
-
layer?: string;
|
|
73
|
-
/**
|
|
74
|
-
* The content to theme. A provider renders **no DOM box of its own** — when a `mode`/`surface` is pinned or
|
|
75
|
-
* the instance is `isolate`d, those are cloned ONTO this child, so in that case it must be a **single**
|
|
76
|
-
* element that forwards `className` / DOM attributes to its root (`Studio`, `WorkbookElement`, and intrinsic
|
|
77
|
-
* elements all do). In the common case (global, no pinned mode) nothing is injected and children render as-is.
|
|
78
|
-
*/
|
|
79
|
-
children?: React.ReactNode;
|
|
80
|
-
}
|
|
81
|
-
/**
|
|
82
|
-
* A thin React wrapper around the CSS-variable theme model — the ergonomic form of the hand-written
|
|
83
|
-
* `<style>` + `data-sxl-theme-*` ceremony (see the "CSS Variables" story). It builds the `--sxl-*` stylesheet
|
|
84
|
-
* from `light`/`dark` token sets (via {@link buildThemeCSS}) and injects it, so the common flow is: render a
|
|
85
|
-
* workbook, wrap it, pass your brand tokens. It renders **no DOM box of its own** — when a mode/surface is
|
|
86
|
-
* pinned or the instance is `isolate`d, those attributes are cloned onto its single child instead.
|
|
87
|
-
*
|
|
88
|
-
* @remarks
|
|
89
|
-
* **Resolution stays in CSS** — this only *emits* CSS and publishes a {@link TokenThemeContextValue} handle.
|
|
90
|
-
* The default is an **override layer over a wrapped component that already defines base + surfaces** (Studio /
|
|
91
|
-
* WorkbookElement); `base`/`surfaces` are the from-scratch escape hatch. Nesting is a **shallow input merge**
|
|
92
|
-
* (base/parent ⊕ own) — a `TokenTheme` is flat, so a shallow spread is the correct merge (the one array token
|
|
93
|
-
* `color-series` is replaced wholesale by design). There is intentionally **no shared-`theme` prop**: put
|
|
94
|
-
* shared tokens in both modes, or in a parent provider both modes inherit (nesting IS the shared layer).
|
|
95
|
-
*/
|
|
96
|
-
export declare const TokenThemeProvider: React.FC<TokenThemeProviderProps>;
|
|
97
|
-
//# sourceMappingURL=TokenThemeProvider.d.ts.map
|