@ng-prism/core 22.3.0 → 22.4.1

package/dist/shared/measure.type.d.ts

@@ -0,0 +1,52 @@
+/**
+ * The measuring tool measures geometry, not cascade: a point knows the edge
+ * it sits on, but not the CSS property that produced it. Mapping pixels to a
+ * property is deliberately a follow-up step, see Spec §13.
+ */
+export type SnapKind = 'border' | 'padding' | 'content';
+export type EdgeSide = 'top' | 'right' | 'bottom' | 'left';
+/** What a point snapped to — `null` when no target was within tolerance. */
+export interface SnapRef {
+    kind: SnapKind;
+    side: EdgeSide;
+    from: Element;
+}
+/**
+ * A measure point in `.demo-wrap`-local CSS pixels.
+ *
+ * Not in screen coordinates: `.demo-wrap` carries
+ * `transform: scale(var(--zoom))`, and local coordinates turn the distance
+ * into a CSS-pixel distance with no further division. Zooming after a pin is
+ * placed then does not shift it relative to the specimen.
+ */
+export interface MeasurePoint {
+    x: number;
+    y: number;
+    snap: SnapRef | null;
+}
+export interface Measurement {
+    a: MeasurePoint;
+    b: MeasurePoint;
+}
+/**
+ * How close the pointer has to come to an edge, in **screen** pixels.
+ *
+ * Screen and not document pixels, because the tolerance describes a
+ * precision of the hand and not a property of the document: it has to feel
+ * the same at 50% zoom as at 200%. Same value as `VIEWPORT_SNAP_TOLERANCE`,
+ * for the same reason.
+ */
+export declare const MEASURE_SNAP_TOLERANCE = 8;
+/**
+ * The span, in CSS pixels, above which the value fits between the end ticks.
+ *
+ * Below it the ticks and the number overlap, and the measurement becomes
+ * unreadable exactly where it needs to be most precise. The value then
+ * moves outside instead.
+ */
+export declare const MEASURE_LABEL_MIN_SPAN = 28;
+/** How far the value steps aside, perpendicular to the line, for short spans. */
+export declare const MEASURE_LABEL_OFFSET = 15;
+/** Length of an end tick, centered on the endpoint. */
+export declare const MEASURE_TICK_LENGTH = 7;
+//# sourceMappingURL=measure.type.d.ts.map

package/dist/shared/measure.type.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"measure.type.d.ts","sourceRoot":"","sources":["../../src/shared/measure.type.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,MAAM,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,SAAS,CAAC;AAExD,MAAM,MAAM,QAAQ,GAAG,KAAK,GAAG,OAAO,GAAG,QAAQ,GAAG,MAAM,CAAC;AAE3D,4EAA4E;AAC5E,MAAM,WAAW,OAAO;IACpB,IAAI,EAAE,QAAQ,CAAC;IACf,IAAI,EAAE,QAAQ,CAAC;IACf,IAAI,EAAE,OAAO,CAAC;CACjB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,YAAY;IACzB,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,IAAI,EAAE,OAAO,GAAG,IAAI,CAAC;CACxB;AAED,MAAM,WAAW,WAAW;IACxB,CAAC,EAAE,YAAY,CAAC;IAChB,CAAC,EAAE,YAAY,CAAC;CACnB;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,sBAAsB,IAAI,CAAC;AAExC;;;;;;GAMG;AACH,eAAO,MAAM,sBAAsB,KAAK,CAAC;AAEzC,iFAAiF;AACjF,eAAO,MAAM,oBAAoB,KAAK,CAAC;AAEvC,uDAAuD;AACvD,eAAO,MAAM,mBAAmB,IAAI,CAAC"}

package/dist/shared/measure.type.js

@@ -0,0 +1,21 @@
+/**
+ * How close the pointer has to come to an edge, in **screen** pixels.
+ *
+ * Screen and not document pixels, because the tolerance describes a
+ * precision of the hand and not a property of the document: it has to feel
+ * the same at 50% zoom as at 200%. Same value as `VIEWPORT_SNAP_TOLERANCE`,
+ * for the same reason.
+ */
+export const MEASURE_SNAP_TOLERANCE = 8;
+/**
+ * The span, in CSS pixels, above which the value fits between the end ticks.
+ *
+ * Below it the ticks and the number overlap, and the measurement becomes
+ * unreadable exactly where it needs to be most precise. The value then
+ * moves outside instead.
+ */
+export const MEASURE_LABEL_MIN_SPAN = 28;
+/** How far the value steps aside, perpendicular to the line, for short spans. */
+export const MEASURE_LABEL_OFFSET = 15;
+/** Length of an end tick, centered on the endpoint. */
+export const MEASURE_TICK_LENGTH = 7;

package/dist/shared/variant-bg.d.ts

@@ -2,37 +2,26 @@ import type { CanvasBg } from './canvas-bg.type.js';
 /**
  * The surface a variant is reported to render on when nothing declares one.
  *
- * An undeclared variant is the "no opinion" case, and `transparent` is the
- * honest capture of no opinion. The alternative, `checker`, patterns over
- * `--prism-bg-surface` — a *theme* token — and capture mode strips the pattern
- * and keeps the colour, so an undeclared variant used to be photographed on
- * whichever theme the runner's browser happened to start in. That is not a
- * neutral default; it is the runner's theme leaking into a baseline. Alpha
- * carries no such dependency, and it is not the thing capture mode's
- * determinism argument rules out: a pattern has a phase that shifts when a
- * centred component resizes, an alpha channel is a per-pixel value that does
- * not move.
- *
- * In the app both values look identical — `transparent` renders as the same
- * checkerboard, which is the UI's way of saying "no surface here". The change
- * is only visible in a capture.
- *
- * The cost is real and worth stating plainly: a runner that does not pass
- * `omitBackground: true` gets an opaque capture over whatever the browser
- * painted, because the page's own backdrop is below every stylesheet. See
+ * `transparent`, because an undeclared variant has no opinion about its
+ * surface. `checker` patterns over `--prism-bg-surface`, a theme token, and
+ * capture mode keeps the colour, so the runner's theme would leak into the
+ * baseline. Alpha has no such dependency and, unlike a pattern, does not shift
+ * when a centred component resizes. In the app both render the same
+ * checkerboard; the difference only shows in a capture.
+ *
+ * A runner must pass `omitBackground: true`, otherwise the capture is opaque
+ * over whatever the browser painted. See
  * `docs/guide/visual-regression.md#capturing-transparency`.
  *
- * What to declare, now that the default no longer decides it for you:
+ * What to declare:
  *
- * - `light` or `dark` when the component was designed against a surface.
- *   Their colours are absolute rather than theme tokens, which is what makes
- *   them stable across runners.
- * - `transparent` when the component's own transparency is the thing under
- *   test — an outlined button, an icon, a divider. Flattening one onto an
- *   opaque colour makes a transparent fill and a painted fill produce the
- *   same pixels.
- * - `dots`, `plain` or `checker` for browsing. All three follow the active
- *   theme, so a baseline recorded on one is only as stable as the theme.
+ * - `light` or `dark` when the component was designed against a surface. Their
+ *   colours are absolute, not theme tokens, so they are stable across runners.
+ * - `transparent` when the component's own transparency is under test (an
+ *   outlined button, an icon, a divider). On an opaque colour a transparent
+ *   fill and a painted fill produce the same pixels.
+ * - `dots`, `plain` or `checker` for browsing. They follow the active theme, so
+ *   a baseline recorded on one is only as stable as the theme.
  */
 export declare const DEFAULT_VARIANT_BG: CanvasBg;
 /**
@@ -50,7 +39,7 @@ export interface VariantBgSource {
 /**
  * The background a variant *declares*, or `null` when it declares none.
  *
- * Priority is variant, then component. `null` is a meaningful answer — it is
+ * Priority is variant, then component. `null` is a meaningful answer. It is
  * what lets the canvas keep the user's own background choice instead of
  * overwriting it, and what makes the background pill able to say "this is your
  * choice, not the component's".
@@ -64,8 +53,8 @@ export declare function declaredVariantBg(config: VariantBgSource, variantIndex:
 /**
  * The background a variant renders on, always resolved to a concrete value.
  *
- * This is the answer external tooling needs — a screenshot runner cannot act
- * on "nothing declared" — and the one capture mode paints, so the value
+ * This is the answer external tooling needs, since a screenshot runner cannot act
+ * on "nothing declared". It is also what capture mode paints, so the value
  * reported by `__PRISM_MANIFEST__` and the pixels in the capture agree.
  */
 export declare function resolveVariantBg(config: VariantBgSource, variantIndex: number): CanvasBg;

package/dist/shared/variant-bg.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"variant-bg.d.ts","sourceRoot":"","sources":["../../src/shared/variant-bg.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAEpD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,eAAO,MAAM,kBAAkB,EAAE,QAAwB,CAAC;AAE1D;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC5B,EAAE,CAAC,EAAE,QAAQ,CAAC;IACd,QAAQ,CAAC,EAAE,SAAS;QAAE,EAAE,CAAC,EAAE,QAAQ,CAAA;KAAE,EAAE,CAAC;CAC3C;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,GAAG,QAAQ,GAAG,IAAI,CAEhG;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,GAAG,QAAQ,CAExF"}
+{"version":3,"file":"variant-bg.d.ts","sourceRoot":"","sources":["../../src/shared/variant-bg.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAEpD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,kBAAkB,EAAE,QAAwB,CAAC;AAE1D;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC5B,EAAE,CAAC,EAAE,QAAQ,CAAC;IACd,QAAQ,CAAC,EAAE,SAAS;QAAE,EAAE,CAAC,EAAE,QAAQ,CAAA;KAAE,EAAE,CAAC;CAC3C;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,GAAG,QAAQ,GAAG,IAAI,CAEhG;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,GAAG,QAAQ,CAExF"}

package/dist/shared/variant-bg.js

@@ -1,43 +1,32 @@
 /**
  * The surface a variant is reported to render on when nothing declares one.
  *
- * An undeclared variant is the "no opinion" case, and `transparent` is the
- * honest capture of no opinion. The alternative, `checker`, patterns over
- * `--prism-bg-surface` — a *theme* token — and capture mode strips the pattern
- * and keeps the colour, so an undeclared variant used to be photographed on
- * whichever theme the runner's browser happened to start in. That is not a
- * neutral default; it is the runner's theme leaking into a baseline. Alpha
- * carries no such dependency, and it is not the thing capture mode's
- * determinism argument rules out: a pattern has a phase that shifts when a
- * centred component resizes, an alpha channel is a per-pixel value that does
- * not move.
- *
- * In the app both values look identical — `transparent` renders as the same
- * checkerboard, which is the UI's way of saying "no surface here". The change
- * is only visible in a capture.
- *
- * The cost is real and worth stating plainly: a runner that does not pass
- * `omitBackground: true` gets an opaque capture over whatever the browser
- * painted, because the page's own backdrop is below every stylesheet. See
+ * `transparent`, because an undeclared variant has no opinion about its
+ * surface. `checker` patterns over `--prism-bg-surface`, a theme token, and
+ * capture mode keeps the colour, so the runner's theme would leak into the
+ * baseline. Alpha has no such dependency and, unlike a pattern, does not shift
+ * when a centred component resizes. In the app both render the same
+ * checkerboard; the difference only shows in a capture.
+ *
+ * A runner must pass `omitBackground: true`, otherwise the capture is opaque
+ * over whatever the browser painted. See
  * `docs/guide/visual-regression.md#capturing-transparency`.
  *
- * What to declare, now that the default no longer decides it for you:
+ * What to declare:
  *
- * - `light` or `dark` when the component was designed against a surface.
- *   Their colours are absolute rather than theme tokens, which is what makes
- *   them stable across runners.
- * - `transparent` when the component's own transparency is the thing under
- *   test — an outlined button, an icon, a divider. Flattening one onto an
- *   opaque colour makes a transparent fill and a painted fill produce the
- *   same pixels.
- * - `dots`, `plain` or `checker` for browsing. All three follow the active
- *   theme, so a baseline recorded on one is only as stable as the theme.
+ * - `light` or `dark` when the component was designed against a surface. Their
+ *   colours are absolute, not theme tokens, so they are stable across runners.
+ * - `transparent` when the component's own transparency is under test (an
+ *   outlined button, an icon, a divider). On an opaque colour a transparent
+ *   fill and a painted fill produce the same pixels.
+ * - `dots`, `plain` or `checker` for browsing. They follow the active theme, so
+ *   a baseline recorded on one is only as stable as the theme.
  */
 export const DEFAULT_VARIANT_BG = 'transparent';
 /**
  * The background a variant *declares*, or `null` when it declares none.
  *
- * Priority is variant, then component. `null` is a meaningful answer — it is
+ * Priority is variant, then component. `null` is a meaningful answer. It is
  * what lets the canvas keep the user's own background choice instead of
  * overwriting it, and what makes the background pill able to say "this is your
  * choice, not the component's".
@@ -53,8 +42,8 @@ export function declaredVariantBg(config, variantIndex) {
 /**
  * The background a variant renders on, always resolved to a concrete value.
  *
- * This is the answer external tooling needs — a screenshot runner cannot act
- * on "nothing declared" — and the one capture mode paints, so the value
+ * This is the answer external tooling needs, since a screenshot runner cannot act
+ * on "nothing declared". It is also what capture mode paints, so the value
  * reported by `__PRISM_MANIFEST__` and the pixels in the capture agree.
  */
 export function resolveVariantBg(config, variantIndex) {

package/dist/shared/viewport.type.d.ts

@@ -1,20 +1,18 @@
 /**
  * The canvas viewport: one nullable number, not a device list.
  *
- * The question this tool answers is "where does the layout break", not "how
- * does it look on a Pixel 8" — so the presets below are plain widths and carry
- * no device names. A name would imply a simulation the constraint does not
- * perform: it narrows the box and nothing else. Media queries still read the
- * real browser viewport; only `@container` rules respond.
+ * The tool is for finding where a layout breaks, so the presets are plain
+ * widths without device names. A device name would suggest a simulation; the
+ * constraint only narrows the box. Media queries still read the real browser
+ * viewport; only `@container` rules respond.
  */
 /**
  * The narrowest the constraint will go.
  *
- * Below any real device on purpose. The presets cover the widths people design
- * against; this floor is for the other half of the job — dragging past where a
- * layout still works to find the point at which it gives up. A floor set to the
- * narrowest real phone would put that point out of reach on exactly the
- * components most worth checking.
+ * Below any real device. The presets cover the widths people design against;
+ * the floor lets a drag go past them to find where a layout breaks. A floor at
+ * the narrowest real phone would hide that point for the components most worth
+ * checking.
  */
 export declare const VIEWPORT_MIN = 100;
 /** Wide enough for a desktop breakpoint, short of the point where the stage scrolls on any realistic screen. */
@@ -27,21 +25,19 @@ export declare const VIEWPORT_SNAP_TOLERANCE = 8;
  * The named widths, as numbers.
  *
  * Common CSS breakpoints plus the two phone widths that actually differ from
- * them. Rendered as the "Width" group in the canvas tools menu, exactly like
- * the zoom chooser next to it.
+ * them. Rendered as the "Width" group in the canvas tools menu, like the zoom
+ * chooser next to it.
  */
 export declare const VIEWPORT_SNAPS: readonly number[];
 /**
  * `width` brought inside the legal range and onto a whole pixel.
  *
- * Lives beside the bounds it enforces rather than next to the canvas's
- * snapping: the clamp is the service's business — it is what keeps a stored
- * or programmatic width legal — and a service reaching into the canvas UI
- * folder for arithmetic over these two constants was the wrong direction.
+ * Lives next to the bounds, not the canvas snapping, because the service uses
+ * it to keep stored and programmatic widths legal and should not import from
+ * the canvas UI folder.
  *
- * Rounded rather than truncated: the value is read back out as a label on the
- * canvas, and `389.6 px` under a drag reads as a rendering fault rather than as
- * the sub-pixel arithmetic it is.
+ * Rounded, not truncated: the value is shown as a label on the canvas, and
+ * `389.6 px` during a drag looks like a rendering bug.
  */
 export declare function clampViewportWidth(width: number): number;
 //# sourceMappingURL=viewport.type.d.ts.map

package/dist/shared/viewport.type.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"viewport.type.d.ts","sourceRoot":"","sources":["../../src/shared/viewport.type.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH;;;;;;;;GAQG;AACH,eAAO,MAAM,YAAY,MAAM,CAAC;AAEhC,gHAAgH;AAChH,eAAO,MAAM,YAAY,OAAO,CAAC;AAEjC,sEAAsE;AACtE,eAAO,MAAM,gBAAgB,MAAM,CAAC;AAEpC,0EAA0E;AAC1E,eAAO,MAAM,uBAAuB,IAAI,CAAC;AAEzC;;;;;;GAMG;AACH,eAAO,MAAM,cAAc,EAAE,SAAS,MAAM,EAAoC,CAAC;AAEjF;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAExD"}
+{"version":3,"file":"viewport.type.d.ts","sourceRoot":"","sources":["../../src/shared/viewport.type.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;;;;;;GAOG;AACH,eAAO,MAAM,YAAY,MAAM,CAAC;AAEhC,gHAAgH;AAChH,eAAO,MAAM,YAAY,OAAO,CAAC;AAEjC,sEAAsE;AACtE,eAAO,MAAM,gBAAgB,MAAM,CAAC;AAEpC,0EAA0E;AAC1E,eAAO,MAAM,uBAAuB,IAAI,CAAC;AAEzC;;;;;;GAMG;AACH,eAAO,MAAM,cAAc,EAAE,SAAS,MAAM,EAAoC,CAAC;AAEjF;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAExD"}

package/dist/shared/viewport.type.js

@@ -1,20 +1,18 @@
 /**
  * The canvas viewport: one nullable number, not a device list.
  *
- * The question this tool answers is "where does the layout break", not "how
- * does it look on a Pixel 8" — so the presets below are plain widths and carry
- * no device names. A name would imply a simulation the constraint does not
- * perform: it narrows the box and nothing else. Media queries still read the
- * real browser viewport; only `@container` rules respond.
+ * The tool is for finding where a layout breaks, so the presets are plain
+ * widths without device names. A device name would suggest a simulation; the
+ * constraint only narrows the box. Media queries still read the real browser
+ * viewport; only `@container` rules respond.
  */
 /**
  * The narrowest the constraint will go.
  *
- * Below any real device on purpose. The presets cover the widths people design
- * against; this floor is for the other half of the job — dragging past where a
- * layout still works to find the point at which it gives up. A floor set to the
- * narrowest real phone would put that point out of reach on exactly the
- * components most worth checking.
+ * Below any real device. The presets cover the widths people design against;
+ * the floor lets a drag go past them to find where a layout breaks. A floor at
+ * the narrowest real phone would hide that point for the components most worth
+ * checking.
  */
 export const VIEWPORT_MIN = 100;
 /** Wide enough for a desktop breakpoint, short of the point where the stage scrolls on any realistic screen. */
@@ -27,21 +25,19 @@ export const VIEWPORT_SNAP_TOLERANCE = 8;
  * The named widths, as numbers.
  *
  * Common CSS breakpoints plus the two phone widths that actually differ from
- * them. Rendered as the "Width" group in the canvas tools menu, exactly like
- * the zoom chooser next to it.
+ * them. Rendered as the "Width" group in the canvas tools menu, like the zoom
+ * chooser next to it.
  */
 export const VIEWPORT_SNAPS = [320, 390, 480, 640, 768, 1024];
 /**
  * `width` brought inside the legal range and onto a whole pixel.
  *
- * Lives beside the bounds it enforces rather than next to the canvas's
- * snapping: the clamp is the service's business — it is what keeps a stored
- * or programmatic width legal — and a service reaching into the canvas UI
- * folder for arithmetic over these two constants was the wrong direction.
+ * Lives next to the bounds, not the canvas snapping, because the service uses
+ * it to keep stored and programmatic widths legal and should not import from
+ * the canvas UI folder.
  *
- * Rounded rather than truncated: the value is read back out as a label on the
- * canvas, and `389.6 px` under a drag reads as a rendering fault rather than as
- * the sub-pixel arithmetic it is.
+ * Rounded, not truncated: the value is shown as a label on the canvas, and
+ * `389.6 px` during a drag looks like a rendering bug.
  */
 export function clampViewportWidth(width) {
     return Math.round(Math.max(VIEWPORT_MIN, Math.min(VIEWPORT_MAX, width)));

package/dist/transformer/showcase-strip.transformer.js

@@ -168,7 +168,7 @@ export function stripShowcaseDecorators(source, fileName = 'file.ts') {
     const leak = findShowcaseLeak(audited, importInfo.localNames);
     if (leak) {
         throw new Error(`[ng-prism] Showcase reference '${leak.name}' left in output after stripping at ${fileName}:${leak.line}. ` +
-            `The Showcase import was removed but a reference remains — this would cause a ReferenceError at runtime. ` +
+            `The Showcase import was removed but a reference remains, which would cause a ReferenceError at runtime. ` +
             `This is a transformer bug; please report the input source.`);
     }
     return output;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ng-prism/core",
-  "version": "22.3.0",
-  "description": "ng-prism — the Angular-native Storybook alternative. Lightweight component showcase with @Showcase decorator, no story files needed.",
+  "version": "22.4.1",
+  "description": "ng-prism: the Angular-native Storybook alternative. Lightweight component showcase with @Showcase decorator, no story files needed.",
   "keywords": [
     "ng-prism",
     "angular",
@@ -100,9 +100,9 @@
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/dyingangel666/ng-prism.git",
+    "url": "https://github.com/ng-prism/ng-prism.git",
     "directory": "packages/ng-prism"
   },
-  "homepage": "https://dyingangel666.github.io/ng-prism/",
-  "bugs": "https://github.com/dyingangel666/ng-prism/issues"
+  "homepage": "https://ng-prism.github.io/ng-prism/",
+  "bugs": "https://github.com/ng-prism/ng-prism/issues"
 }