dotquilt 0.1.1 → 0.2.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.
@@ -0,0 +1,48 @@
1
+ import { type StylePolicy } from './types.js';
2
+ export { type StaticTableLayout, staticTableLayout, } from './internal/table-model.js';
3
+ /**
4
+ * The `slot` of the wrapper's own `<style>` or `<link>` inside a host: no
5
+ * slot has this name, so it never shows or counts as content, and its rules
6
+ * apply all the same.
7
+ */
8
+ export declare const wrapperStyleSlot = "dotquilt-wrapper-style";
9
+ /** Marks the wrapper-owned node that holds a loader's static drawing. */
10
+ export declare const wrapperStatic = "data-dotquilt-wrapper-static";
11
+ /** Marks the wrapper-owned element filling a region slot. */
12
+ export declare const wrapperSlot = "data-dotquilt-wrapper-slot";
13
+ /** On a region host that has no placeholder to show. */
14
+ export declare const wrapperEmpty = "data-dotquilt-wrapper-empty";
15
+ export declare function wrapperSkeletonStyles(): readonly string[];
16
+ export declare function wrapperLineStyles(): readonly string[];
17
+ export declare function wrapperCircleStyles(): readonly string[];
18
+ export declare function wrapperSkeletonTextStyles(): readonly string[];
19
+ export declare function wrapperTypingStyles(): readonly string[];
20
+ export declare function wrapperTextStyles(): readonly string[];
21
+ export declare function wrapperTextMarkStyles(): readonly string[];
22
+ export declare function wrapperChartStyles(): readonly string[];
23
+ export declare function wrapperChartMarkStyles(): readonly string[];
24
+ export declare function wrapperTableStyles(): readonly string[];
25
+ /** Static rules for squares and dashes; add them only when drawing one. */
26
+ export declare function wrapperSkeletonMarkStyles(): readonly string[];
27
+ export declare function wrapperLineMarkStyles(): readonly string[];
28
+ export declare function wrapperCircleMarkStyles(): readonly string[];
29
+ export declare function wrapperSkeletonTextMarkStyles(): readonly string[];
30
+ export declare function wrapperTypingMarkStyles(): readonly string[];
31
+ /**
32
+ * A region's slots. While pending, the placeholder is in flow, with any
33
+ * content below it, so the first HTML reserves its space (and without
34
+ * JavaScript the content stays visible under it). The refresh cue lies over
35
+ * the content.
36
+ */
37
+ export declare const wrapperRegionStyles: readonly string[];
38
+ /** Checks a style policy the way the elements do, before any markup uses it. */
39
+ export declare function wrapperPolicy(value: StylePolicy | undefined): StylePolicy;
40
+ /** The host attributes that carry a style policy to the element. */
41
+ export declare function wrapperPolicyAttributes(policy: StylePolicy): Readonly<Record<string, string>>;
42
+ /** Whether a mark needs its extra static rules (the default dot doesn't). */
43
+ export declare const wrapperNeedsMarkStyles: (policy: StylePolicy, mark: unknown) => boolean;
44
+ /** SkeletonText's line count and widths, normalized as the element does. */
45
+ export declare function wrapperSkeletonLines(lines: number | undefined, widths: readonly number[] | undefined): {
46
+ readonly count: number;
47
+ readonly widths: readonly number[];
48
+ };
@@ -0,0 +1,166 @@
1
+ /**
2
+ * For framework packages (`@dotquilt/vue`, `@dotquilt/svelte`,
3
+ * `@dotquilt/angular`), not applications: what a component renders around a
4
+ * native element, so server HTML shows the placeholder before the element is
5
+ * defined, and hydration never has to match nodes the element changed.
6
+ *
7
+ * A component renders, as plain markup it owns:
8
+ * - the host with its initial attributes and `wrapperPolicyAttributes()`;
9
+ * - inside it, first, a `<style slot="dotquilt-wrapper-style">` with the
10
+ * family's styles below (or a `<link>` for an external policy);
11
+ * - then `<span data-dotquilt-wrapper-static aria-hidden="true">`
12
+ * holding the static drawing (`<span data-dotquilt-static>` and its
13
+ * contents), which stays put: once defined, the element draws in its
14
+ * shadow root and no longer shows light-DOM children it doesn't slot.
15
+ * It then registers the element on the client and delivers every option
16
+ * through `update()`.
17
+ *
18
+ * Every rule here applies only while the element is undefined or waiting for
19
+ * an external stylesheet (`:state(unstyled)`). Pure and DOM-free.
20
+ */
21
+ import { staticCircleMarkStyles, staticCircleStyles, staticLineMarkStyles, staticLineStyles, staticTextMarkStyles, staticTextStyles, staticTypingMarkStyles, staticTypingStyles, } from './static-catalog-styles.js';
22
+ import { staticSkeletonMarkStyles, staticSkeletonStyles } from './styles.js';
23
+ import { LoaderConfigurationError } from './types.js';
24
+ export { staticTableLayout, } from './internal/table-model.js';
25
+ import { staticChartMarkStyles, staticChartStyles } from './chart-styles.js';
26
+ import { staticTableStyles } from './table-styles.js';
27
+ import { staticTextLoaderMarkStyles, staticTextLoaderStyles, } from './text-styles.js';
28
+ /**
29
+ * The `slot` of the wrapper's own `<style>` or `<link>` inside a host: no
30
+ * slot has this name, so it never shows or counts as content, and its rules
31
+ * apply all the same.
32
+ */
33
+ export const wrapperStyleSlot = 'dotquilt-wrapper-style';
34
+ /** Marks the wrapper-owned node that holds a loader's static drawing. */
35
+ export const wrapperStatic = 'data-dotquilt-wrapper-static';
36
+ /** Marks the wrapper-owned element filling a region slot. */
37
+ export const wrapperSlot = 'data-dotquilt-wrapper-slot';
38
+ /** On a region host that has no placeholder to show. */
39
+ export const wrapperEmpty = 'data-dotquilt-wrapper-empty';
40
+ /**
41
+ * The element while it's undefined or waiting for its stylesheet, at zero
42
+ * specificity: the page's own classes win over these rules, as they do over
43
+ * the element's shadow styles once it's defined.
44
+ */
45
+ const beforeDefinition = (tag) => `:where(${tag}:is(:not(:defined),:state(unstyled)))`;
46
+ /** Lowers every element selector in rules core already scopes. */
47
+ const lowered = (css) => Object.freeze(css.map((text) => text.replace(/(?<!:where\()(dotquilt-[a-z-]+):is\(:not\(:defined\),:state\(unstyled\)\)/g, (_, tag) => beforeDefinition(tag))));
48
+ function scoped(css, tag, hidden) {
49
+ const rules = css.map((text) => text.replaceAll(tag, beforeDefinition(tag)));
50
+ return Object.freeze(hidden
51
+ ? rules.concat(`${beforeDefinition(tag)}[hidden]{display:none}`)
52
+ : rules);
53
+ }
54
+ // Getters, not constants: a bundle keeps only the families a component
55
+ // actually draws, even though the shared style modules do work as they load.
56
+ const cache = new Map();
57
+ const lazily = (key, make) => {
58
+ let value = cache.get(key);
59
+ if (!value) {
60
+ value = make();
61
+ cache.set(key, value);
62
+ }
63
+ return value;
64
+ };
65
+ const styles = (key, css, tag, hidden) => lazily(key, () => scoped(css(), tag, hidden));
66
+ export function wrapperSkeletonStyles() {
67
+ return styles('skeleton', () => staticSkeletonStyles, 'dotquilt-skeleton-block', true);
68
+ }
69
+ export function wrapperLineStyles() {
70
+ return styles('line', () => staticLineStyles, 'dotquilt-skeleton-line', true);
71
+ }
72
+ export function wrapperCircleStyles() {
73
+ return styles('circle', () => staticCircleStyles, 'dotquilt-skeleton-circle', true);
74
+ }
75
+ export function wrapperSkeletonTextStyles() {
76
+ return styles('skeleton-text', () => staticTextStyles, 'dotquilt-skeleton-text', true);
77
+ }
78
+ export function wrapperTypingStyles() {
79
+ return styles('typing',
80
+ // The wrapper's own node must not add a second inline baseline.
81
+ () => staticTypingStyles.concat(`dotquilt-typing-dots [${wrapperStatic}]{display:contents}`), 'dotquilt-typing-dots', true);
82
+ }
83
+ export function wrapperTextStyles() {
84
+ return lazily('text', () => lowered(staticTextLoaderStyles));
85
+ }
86
+ export function wrapperTextMarkStyles() {
87
+ return lazily('text-marks', () => lowered(staticTextLoaderMarkStyles));
88
+ }
89
+ export function wrapperChartStyles() {
90
+ return lazily('chart', () => lowered(staticChartStyles));
91
+ }
92
+ export function wrapperChartMarkStyles() {
93
+ return lazily('chart-marks', () => lowered(staticChartMarkStyles));
94
+ }
95
+ export function wrapperTableStyles() {
96
+ return lazily('table', () => lowered(staticTableStyles));
97
+ }
98
+ /** Static rules for squares and dashes; add them only when drawing one. */
99
+ export function wrapperSkeletonMarkStyles() {
100
+ return styles('skeleton-marks', () => staticSkeletonMarkStyles, 'dotquilt-skeleton-block', false);
101
+ }
102
+ export function wrapperLineMarkStyles() {
103
+ return styles('line-marks', () => staticLineMarkStyles, 'dotquilt-skeleton-line', false);
104
+ }
105
+ export function wrapperCircleMarkStyles() {
106
+ return styles('circle-marks', () => staticCircleMarkStyles, 'dotquilt-skeleton-circle', false);
107
+ }
108
+ export function wrapperSkeletonTextMarkStyles() {
109
+ return styles('skeleton-text-marks', () => staticTextMarkStyles, 'dotquilt-skeleton-text', false);
110
+ }
111
+ export function wrapperTypingMarkStyles() {
112
+ return styles('typing-marks', () => staticTypingMarkStyles, 'dotquilt-typing-dots', false);
113
+ }
114
+ const region = beforeDefinition('dotquilt-region');
115
+ /**
116
+ * A region's slots. While pending, the placeholder is in flow, with any
117
+ * content below it, so the first HTML reserves its space (and without
118
+ * JavaScript the content stays visible under it). The refresh cue lies over
119
+ * the content.
120
+ */
121
+ export const wrapperRegionStyles = [
122
+ `${region}{display:flow-root;position:relative}${region}[hidden]{display:none}${region}>[${wrapperSlot}]{position:absolute;inset:0;pointer-events:none}${region}[state=pending]>[slot=placeholder]{position:relative}${region}:not([state=pending])>[slot=placeholder],${region}:not([state=refreshing])>[slot=refresh-indicator]{display:none}${region}[state=pending][${wrapperEmpty}]::before{content:"";position:absolute;inset:0;min-height:1em;border:1px dotted currentColor}`,
123
+ ];
124
+ /** Checks a style policy the way the elements do, before any markup uses it. */
125
+ export function wrapperPolicy(value) {
126
+ const policy = value ?? { mode: 'inline' };
127
+ if (!policy ||
128
+ (policy.mode !== 'inline' && policy.mode !== 'external') ||
129
+ (policy.mode === 'inline' &&
130
+ policy.nonce !== undefined &&
131
+ (typeof policy.nonce !== 'string' || policy.nonce.length > 256)) ||
132
+ (policy.mode === 'external' &&
133
+ (typeof policy.href !== 'string' ||
134
+ policy.href.length > 2048 ||
135
+ !/^(https?:\/\/|\/[^/]|\.\.?\/)/.test(policy.href))))
136
+ throw new LoaderConfigurationError('invalid-style-policy', 'Invalid style policy');
137
+ return Object.freeze({ ...policy });
138
+ }
139
+ /** The host attributes that carry a style policy to the element. */
140
+ export function wrapperPolicyAttributes(policy) {
141
+ if (policy.mode === 'external')
142
+ return { 'data-dotquilt-style-href': policy.href };
143
+ return policy.nonce === undefined ? {} : { nonce: policy.nonce };
144
+ }
145
+ /** Whether a mark needs its extra static rules (the default dot doesn't). */
146
+ export const wrapperNeedsMarkStyles = (policy, mark) => policy.mode !== 'external' && (mark === 'dash' || mark === 'square');
147
+ /** SkeletonText's line count and widths, normalized as the element does. */
148
+ export function wrapperSkeletonLines(lines, widths) {
149
+ const count = lines !== undefined && Number.isInteger(lines) && lines > 0
150
+ ? Math.min(lines, 50)
151
+ : 3;
152
+ return {
153
+ count,
154
+ widths: Array.from({ length: count }, (_, index) => {
155
+ const width = widths?.[index];
156
+ return typeof width === 'number' &&
157
+ Number.isFinite(width) &&
158
+ width > 0 &&
159
+ width <= 1
160
+ ? width
161
+ : count > 1 && index === count - 1
162
+ ? 0.6
163
+ : 1;
164
+ }),
165
+ };
166
+ }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "dotquilt",
3
- "version": "0.1.1",
3
+ "version": "0.2.0",
4
4
  "description": "Loading placeholders that hold the shape of your content, then hand over to it. Native Web Components.",
5
5
  "type": "module",
6
6
  "license": "MIT",
@@ -12,11 +12,17 @@
12
12
  "loader",
13
13
  "web-components",
14
14
  "accessibility",
15
- "ssr"
15
+ "ssr",
16
+ "skeleton-loader",
17
+ "skeleton loader",
18
+ "loading placeholder",
19
+ "custom-elements"
16
20
  ],
17
21
  "sideEffects": [
18
22
  "**/*.css"
19
23
  ],
24
+ "customElements": "dist/custom-elements.json",
25
+ "web-types": "dist/web-types.json",
20
26
  "files": [
21
27
  "dist",
22
28
  "README.md",
@@ -79,6 +85,10 @@
79
85
  "types": "./dist/register-all.d.ts",
80
86
  "import": "./dist/register-all.js"
81
87
  },
88
+ "./wrapper": {
89
+ "types": "./dist/wrapper.d.ts",
90
+ "import": "./dist/wrapper.js"
91
+ },
82
92
  "./styles/*.css": "./dist/*.css"
83
93
  },
84
94
  "scripts": {