@pantoken/utils 0.1.0 → 0.2.1

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 (3) hide show
  1. package/dist/index.d.mts +62 -1
  2. package/dist/index.mjs +119 -1
  3. package/package.json +25 -14
package/dist/index.d.mts CHANGED
@@ -1,5 +1,66 @@
1
1
  import { Token } from "@pantoken/model";
2
2
 
3
+ //#region src/declarations.d.ts
4
+ /**
5
+ * The two composite custom-property systems that sit *below* the component library but *above* the raw
6
+ * token IR: the `--instui-elevation-*` shadow scale and the `--instui-focus-outline-*` ring variables
7
+ * (plus the zero-specificity `:focus-visible` ring rules). They're bespoke composites — hardcoded
8
+ * geometry/constants combined with themed token references — so they can't be plain IR tokens, yet both
9
+ * `@pantoken/css` (which emits them into the token sheet) and `@pantoken/components` (which documents
10
+ * them as `@declaration` records and reuses them for the base/pendo sheets) need them. Keeping them here,
11
+ * in the shared upstream-free helpers package, lets `@pantoken/css` own the emission without an upward
12
+ * dependency on `@pantoken/components`.
13
+ *
14
+ * These are pure string builders — no Node imports, no cssdoc/`Definition` concerns — so the
15
+ * browser-facing graphs that pull them in stay Node-free.
16
+ *
17
+ * @module
18
+ */
19
+ /**
20
+ * Every elevation level and alias emitted as `--instui-elevation-<name>` (`resting`, `above`,
21
+ * `topmost`, `depth1`–`depth3`, `card`, `cardHover`). Derived from the geometry + alias maps.
22
+ */
23
+ declare const ELEVATION_NAMES: readonly string[];
24
+ /**
25
+ * The `--instui-elevation-*` name/value pairs (each a multi-layer `box-shadow`). Values reference the
26
+ * themed drop-shadow colour tokens, so they adapt per theme wherever a token sheet is loaded.
27
+ *
28
+ * @returns One `[customProperty, value]` pair per level and alias.
29
+ *
30
+ * @example
31
+ * ```ts
32
+ * import { elevationDeclarations } from "@pantoken/utils";
33
+ *
34
+ * elevationDeclarations(); // [["--instui-elevation-resting", "…"], ["--instui-elevation-above", "…"], …]
35
+ * ```
36
+ */
37
+ declare function elevationDeclarations(): [name: string, value: string][];
38
+ /** The elements the ring applies to by default (the common interactive/focusable elements). */
39
+ declare const FOCUSABLE_SELECTOR = "a, button, input, select, textarea, summary, [tabindex]";
40
+ /**
41
+ * The `--instui-focus-outline-*` name/value pairs the ring rules read. Colour/width/offset reference
42
+ * the themed shared focus tokens; the transition, line style, and inset are constants.
43
+ *
44
+ * @returns One `[customProperty, value]` pair per focus-ring variable.
45
+ *
46
+ * @example
47
+ * ```ts
48
+ * import { focusOutlineDeclarations } from "@pantoken/utils";
49
+ *
50
+ * focusOutlineDeclarations(); // [["--instui-focus-outline-color", "…"], …]
51
+ * ```
52
+ */
53
+ declare function focusOutlineDeclarations(): [name: string, value: string][];
54
+ /**
55
+ * The focus-ring rules for a given focusable selector: a transparent resting ring that transitions in
56
+ * on `:focus-visible`, plus the `-focus-color-*` / `-focus-position-inset` / `-focus-within` /
57
+ * `-without-focus-animation` modifiers. All `:where()`-wrapped, so zero-specificity.
58
+ *
59
+ * @param selector - The focusable selector the base ring applies to (default {@link FOCUSABLE_SELECTOR}).
60
+ * @returns The CSS rules string.
61
+ */
62
+ declare function focusOutlineRules(selector?: string): string;
63
+ //#endregion
3
64
  //#region src/index.d.ts
4
65
  /** The colour mode to collapse `light-dark()` to. */
5
66
  type Mode = "light" | "dark";
@@ -506,4 +567,4 @@ interface TokenUtilityGroup {
506
567
  */
507
568
  declare function tokenUtilitiesCss(groups: readonly TokenUtilityGroup[], options?: UtilityOptions): string;
508
569
  //#endregion
509
- export { ColorUtilityNames, LIGHT_DARK_RE, Mode, ResolveOptions, Rgba, TokenUtilityGroup, UtilityOptions, VAR_RE, camelCase, colorUtilitiesCss, danglingReferences, extractInstuiRefs, makeResolver, parseHexColor, resolveTokens, tokenNames, tokenUtilitiesCss, unknownReferences };
570
+ export { ColorUtilityNames, ELEVATION_NAMES, FOCUSABLE_SELECTOR, LIGHT_DARK_RE, Mode, ResolveOptions, Rgba, TokenUtilityGroup, UtilityOptions, VAR_RE, camelCase, colorUtilitiesCss, danglingReferences, elevationDeclarations, extractInstuiRefs, focusOutlineDeclarations, focusOutlineRules, makeResolver, parseHexColor, resolveTokens, tokenNames, tokenUtilitiesCss, unknownReferences };
package/dist/index.mjs CHANGED
@@ -1,4 +1,122 @@
1
1
  import { regex } from "arkregex";
2
+ //#region src/declarations.ts
3
+ /**
4
+ * The two composite custom-property systems that sit *below* the component library but *above* the raw
5
+ * token IR: the `--instui-elevation-*` shadow scale and the `--instui-focus-outline-*` ring variables
6
+ * (plus the zero-specificity `:focus-visible` ring rules). They're bespoke composites — hardcoded
7
+ * geometry/constants combined with themed token references — so they can't be plain IR tokens, yet both
8
+ * `@pantoken/css` (which emits them into the token sheet) and `@pantoken/components` (which documents
9
+ * them as `@declaration` records and reuses them for the base/pendo sheets) need them. Keeping them here,
10
+ * in the shared upstream-free helpers package, lets `@pantoken/css` own the emission without an upward
11
+ * dependency on `@pantoken/components`.
12
+ *
13
+ * These are pure string builders — no Node imports, no cssdoc/`Definition` concerns — so the
14
+ * browser-facing graphs that pull them in stay Node-free.
15
+ *
16
+ * @module
17
+ */
18
+ /** Per-level geometry (`offset-x offset-y blur`) for the [tighter, wider] shadow layers. */
19
+ const ELEVATION_GEOMETRY = {
20
+ resting: ["0 0.0625rem 0.125rem", "0 0.0625rem 0.1875rem"],
21
+ above: ["0 0.1875rem 0.375rem", "0 0.1875rem 0.375rem"],
22
+ topmost: ["0 0.375rem 0.4375rem", "0 0.625rem 1.75rem"]
23
+ };
24
+ /** Aliases InstUI ships alongside the primary level names. */
25
+ const ELEVATION_ALIASES = {
26
+ depth1: "resting",
27
+ depth2: "above",
28
+ depth3: "topmost",
29
+ card: "resting",
30
+ cardHover: "topmost"
31
+ };
32
+ /**
33
+ * Every elevation level and alias emitted as `--instui-elevation-<name>` (`resting`, `above`,
34
+ * `topmost`, `depth1`–`depth3`, `card`, `cardHover`). Derived from the geometry + alias maps.
35
+ */
36
+ const ELEVATION_NAMES = [...Object.keys(ELEVATION_GEOMETRY), ...Object.keys(ELEVATION_ALIASES)];
37
+ const ELEVATION_COLOR_STRONG = "var(--instui-color-drop-shadow-shadow-color1)";
38
+ const ELEVATION_COLOR_SOFT = "var(--instui-color-drop-shadow-shadow-color2)";
39
+ const elevationShadow = ([tight, wide]) => `${tight} ${ELEVATION_COLOR_SOFT}, ${wide} ${ELEVATION_COLOR_STRONG}`;
40
+ /**
41
+ * The `--instui-elevation-*` name/value pairs (each a multi-layer `box-shadow`). Values reference the
42
+ * themed drop-shadow colour tokens, so they adapt per theme wherever a token sheet is loaded.
43
+ *
44
+ * @returns One `[customProperty, value]` pair per level and alias.
45
+ *
46
+ * @example
47
+ * ```ts
48
+ * import { elevationDeclarations } from "@pantoken/utils";
49
+ *
50
+ * elevationDeclarations(); // [["--instui-elevation-resting", "…"], ["--instui-elevation-above", "…"], …]
51
+ * ```
52
+ */
53
+ function elevationDeclarations() {
54
+ return [...Object.entries(ELEVATION_GEOMETRY), ...Object.entries(ELEVATION_ALIASES).map(([alias, base]) => [alias, ELEVATION_GEOMETRY[base]])].map(([name, geo]) => [`--instui-elevation-${name}`, elevationShadow(geo)]);
55
+ }
56
+ /** The elements the ring applies to by default (the common interactive/focusable elements). */
57
+ const FOCUSABLE_SELECTOR = "a, button, input, select, textarea, summary, [tabindex]";
58
+ const focusShared = (name) => `var(--instui-component-shared-tokens-focus-outline-${name})`;
59
+ /**
60
+ * The `--instui-focus-outline-*` name/value pairs the ring rules read. Colour/width/offset reference
61
+ * the themed shared focus tokens; the transition, line style, and inset are constants.
62
+ *
63
+ * @returns One `[customProperty, value]` pair per focus-ring variable.
64
+ *
65
+ * @example
66
+ * ```ts
67
+ * import { focusOutlineDeclarations } from "@pantoken/utils";
68
+ *
69
+ * focusOutlineDeclarations(); // [["--instui-focus-outline-color", "…"], …]
70
+ * ```
71
+ */
72
+ function focusOutlineDeclarations() {
73
+ return [
74
+ ["--instui-focus-outline-color", focusShared("info-color")],
75
+ ["--instui-focus-outline-color-start", "transparent"],
76
+ ["--instui-focus-outline-width", focusShared("width")],
77
+ ["--instui-focus-outline-offset", focusShared("offset")],
78
+ ["--instui-focus-outline-radius", "var(--instui-border-radius-md)"],
79
+ ["--instui-focus-outline-style", "solid"],
80
+ ["--instui-focus-outline-transition", "outline-color 0.2s, outline-offset 0.25s"],
81
+ ["--instui-focus-outline-color-success", focusShared("success-color")],
82
+ ["--instui-focus-outline-color-danger", focusShared("danger-color")],
83
+ ["--instui-focus-outline-color-inverse", focusShared("on-color")],
84
+ ["--instui-focus-outline-inset", "0rem"]
85
+ ];
86
+ }
87
+ /**
88
+ * The focus-ring rules for a given focusable selector: a transparent resting ring that transitions in
89
+ * on `:focus-visible`, plus the `-focus-color-*` / `-focus-position-inset` / `-focus-within` /
90
+ * `-without-focus-animation` modifiers. All `:where()`-wrapped, so zero-specificity.
91
+ *
92
+ * @param selector - The focusable selector the base ring applies to (default {@link FOCUSABLE_SELECTOR}).
93
+ * @returns The CSS rules string.
94
+ */
95
+ function focusOutlineRules(selector = FOCUSABLE_SELECTOR) {
96
+ return [
97
+ `:where(${selector}) {`,
98
+ ` outline: var(--instui-focus-outline-width) var(--instui-focus-outline-style) var(--instui-focus-outline-color-start);`,
99
+ ` outline-offset: 0;`,
100
+ ` transition: var(--instui-focus-outline-transition);`,
101
+ `}`,
102
+ `:where(${selector}):where(:focus-visible) {`,
103
+ ` outline-color: var(--instui-focus-outline-color);`,
104
+ ` outline-offset: var(--instui-focus-outline-offset);`,
105
+ ` border-radius: var(--instui-focus-outline-radius);`,
106
+ `}`,
107
+ `:where(.-focus-color-success):where(:focus-visible) { outline-color: var(--instui-focus-outline-color-success); }`,
108
+ `:where(.-focus-color-danger):where(:focus-visible) { outline-color: var(--instui-focus-outline-color-danger); }`,
109
+ `:where(.-focus-color-inverse):where(:focus-visible) { outline-color: var(--instui-focus-outline-color-inverse); }`,
110
+ `:where(.-focus-position-inset):where(:focus-visible) { outline-offset: var(--instui-focus-outline-inset); }`,
111
+ `:where(.-focus-within):where(:focus-within) {`,
112
+ ` outline-color: var(--instui-focus-outline-color);`,
113
+ ` outline-offset: var(--instui-focus-outline-offset);`,
114
+ ` border-radius: var(--instui-focus-outline-radius);`,
115
+ `}`,
116
+ `:where(.-without-focus-animation) { transition: none; }`
117
+ ].join("\n");
118
+ }
119
+ //#endregion
2
120
  //#region src/index.ts
3
121
  /**
4
122
  * `@pantoken/utils` — shared, upstream-free helpers used across the pantoken packages: the token
@@ -283,4 +401,4 @@ function tokenUtilitiesCss(groups, options = {}) {
283
401
  })).join("\n")}\n`;
284
402
  }
285
403
  //#endregion
286
- export { LIGHT_DARK_RE, VAR_RE, camelCase, colorUtilitiesCss, danglingReferences, extractInstuiRefs, makeResolver, parseHexColor, resolveTokens, tokenNames, tokenUtilitiesCss, unknownReferences };
404
+ export { ELEVATION_NAMES, FOCUSABLE_SELECTOR, LIGHT_DARK_RE, VAR_RE, camelCase, colorUtilitiesCss, danglingReferences, elevationDeclarations, extractInstuiRefs, focusOutlineDeclarations, focusOutlineRules, makeResolver, parseHexColor, resolveTokens, tokenNames, tokenUtilitiesCss, unknownReferences };
package/package.json CHANGED
@@ -1,33 +1,44 @@
1
1
  {
2
2
  "name": "@pantoken/utils",
3
- "version": "0.1.0",
3
+ "version": "0.2.1",
4
4
  "description": "Shared pantoken helpers: token reference resolver, typed regexes (arkregex), name-case, and hex-colour parsing.",
5
+ "homepage": "https://pantoken.iywahl.com",
6
+ "bugs": "https://github.com/thedannywahl/pantoken/issues",
5
7
  "license": "MIT",
8
+ "repository": {
9
+ "type": "git",
10
+ "url": "git+https://github.com/thedannywahl/pantoken.git",
11
+ "directory": "packages/utils"
12
+ },
6
13
  "files": [
7
14
  "dist"
8
15
  ],
9
16
  "type": "module",
17
+ "sideEffects": false,
10
18
  "exports": {
11
19
  ".": "./dist/index.mjs",
12
20
  "./package.json": "./package.json"
13
21
  },
14
22
  "publishConfig": {
15
- "access": "public"
16
- },
17
- "dependencies": {
18
- "arkregex": "^0.0.8",
19
- "@pantoken/model": "0.1.0"
20
- },
21
- "devDependencies": {
22
- "@types/node": "^24.13.3",
23
- "typescript": "^6.0.3",
24
- "vite": "npm:@voidzero-dev/vite-plus-core@0.2.4",
25
- "vite-plus": "0.2.4"
23
+ "access": "public",
24
+ "provenance": true
26
25
  },
27
26
  "scripts": {
28
- "build": "vp pack",
29
27
  "dev": "vp pack --watch",
30
28
  "test": "vp test",
31
29
  "check": "vp check"
30
+ },
31
+ "dependencies": {
32
+ "@pantoken/model": "workspace:*",
33
+ "arkregex": "catalog:"
34
+ },
35
+ "devDependencies": {
36
+ "@types/node": "catalog:",
37
+ "typescript": "catalog:",
38
+ "vite": "catalog:",
39
+ "vite-plus": "catalog:"
40
+ },
41
+ "engines": {
42
+ "node": ">=22.18.0"
32
43
  }
33
- }
44
+ }