stablekit.ts 0.2.0

package/dist/stylelint.cjs

@@ -0,0 +1,117 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/stylelint.ts
+var stylelint_exports = {};
+__export(stylelint_exports, {
+  createStyleLint: () => createStyleLint
+});
+module.exports = __toCommonJS(stylelint_exports);
+var pluginRuleName = "stablekit/no-functional-in-utility";
+var descendantColorRuleName = "stablekit/no-descendant-color-in-state";
+function createFunctionalTokenPlugin(prefixes) {
+  const rule = (enabled) => {
+    return (root, result) => {
+      if (!enabled) return;
+      root.walkAtRules("utility", (atRule) => {
+        atRule.walkDecls((decl) => {
+          for (const prefix of prefixes) {
+            if (decl.value.includes(prefix)) {
+              result.warn(
+                `Functional token "${prefix}*" inside @utility. Functional colors belong in scoped selectors (e.g. .badge[data-status="paid"]), not reusable utilities.`,
+                { node: decl }
+              );
+            }
+          }
+        });
+      });
+    };
+  };
+  return {
+    ruleName: pluginRuleName,
+    rule
+  };
+}
+function createDescendantColorPlugin() {
+  const dataAttrWithDescendant = /\[data-[^\]]+\]\s+[.#\w]/;
+  const colorApplyPattern = /\btext-(?!xs|sm|base|lg|xl|2xl|3xl|4xl|5xl|6xl|7xl|8xl|9xl|left|right|center|justify|wrap|nowrap|ellipsis|clip|truncate)\w/;
+  const message = `Setting color on a descendant inside a data-attribute selector. Set color on the [data-*] container and let children inherit via currentColor.`;
+  const rule = (enabled) => {
+    return (root, result) => {
+      if (!enabled) return;
+      root.walkRules((ruleNode) => {
+        if (!dataAttrWithDescendant.test(ruleNode.selector)) return;
+        ruleNode.walkDecls("color", (decl) => {
+          result.warn(message, { node: decl });
+        });
+        ruleNode.walkAtRules("apply", (atRule) => {
+          if (colorApplyPattern.test(atRule.params)) {
+            result.warn(message, { node: atRule });
+          }
+        });
+      });
+    };
+  };
+  return {
+    ruleName: descendantColorRuleName,
+    rule
+  };
+}
+function createStyleLint(options = {}) {
+  const {
+    ignoreTypes = ["html", "body"],
+    functionalTokens = [],
+    files = ["src/**/*.css"]
+  } = options;
+  const plugins = [createDescendantColorPlugin()];
+  if (functionalTokens.length > 0) {
+    plugins.push(createFunctionalTokenPlugin(functionalTokens));
+  }
+  const rules = {
+    // Ban element selectors — use classes and data-attributes instead.
+    "selector-max-type": [
+      0,
+      {
+        ignoreTypes
+      }
+    ],
+    // !important breaks the cascade and fights the architecture.
+    "declaration-no-important": true,
+    // Ban color on descendants inside data-attribute selectors.
+    [descendantColorRuleName]: true,
+    // Ban animating layout properties — causes reflow on every frame.
+    // Use transform (scaleY, translateY) or opacity instead.
+    "declaration-property-value-disallowed-list": [
+      {
+        "transition": [/\b(width|height|max-height|min-height|max-width|min-width|margin|padding|top|right|bottom|left)\b/],
+        "transition-property": [/\b(width|height|max-height|min-height|max-width|min-width|margin|padding|top|right|bottom|left)\b/],
+        "animation-name": []
+      },
+      { message: "Animating layout properties causes reflow. Use transform or opacity instead." }
+    ]
+  };
+  if (functionalTokens.length > 0) {
+    rules[pluginRuleName] = true;
+  }
+  return { files, plugins, rules };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createStyleLint
+});

package/dist/stylelint.d.cts

@@ -0,0 +1,47 @@
+/**
+ * CSS Architecture Linter Factory
+ *
+ * Enforces the Structure → Presentation boundary on the CSS side.
+ *
+ * Four rules:
+ *
+ * 1. Don't target child elements by tag name for visual properties.
+ *    `& svg { color: green }` is wrong — set color on the container
+ *    and let currentColor inherit.
+ *
+ * 2. Don't use !important — it breaks the cascade.
+ *
+ * 3. Don't launder functional color tokens through @utility.
+ *    `@utility text-status-success { color: var(--color-status-active) }`
+ *    turns a functional color into a reusable className, which crosses
+ *    back from Presentation into Structure. Functional tokens belong
+ *    in scoped selectors like `.badge[data-status="paid"]`, not in
+ *    utilities that can spread via @apply or className.
+ *
+ * 4. Don't set color on descendants inside data-attribute selectors.
+ *    `.card[data-status="error"] .icon { color: red }` is wrong —
+ *    set color on the container and let children inherit via currentColor.
+ *
+ * 5. Don't animate layout properties (width, height, margin, padding,
+ *    top/right/bottom/left). These trigger reflow on every frame.
+ *    Use transform (scaleY, translateY) or opacity instead.
+ */
+interface StyleLintOptions {
+    /** Element selectors to allow (e.g. in resets).
+     *  @default ["html", "body"] */
+    ignoreTypes?: string[];
+    /** CSS custom property prefixes that must not appear inside @utility blocks.
+     *  e.g. ["--color-status-", "--color-danger"]
+     *  Any var() referencing these inside @utility is a lint error. */
+    functionalTokens?: string[];
+    /** Glob patterns for files to lint.
+     *  @default ["src/**\/*.css"] */
+    files?: string[];
+}
+declare function createStyleLint(options?: StyleLintOptions): {
+    files: string[];
+    plugins: unknown[];
+    rules: Record<string, unknown>;
+};
+
+export { type StyleLintOptions, createStyleLint };

package/dist/stylelint.d.ts

@@ -0,0 +1,47 @@
+/**
+ * CSS Architecture Linter Factory
+ *
+ * Enforces the Structure → Presentation boundary on the CSS side.
+ *
+ * Four rules:
+ *
+ * 1. Don't target child elements by tag name for visual properties.
+ *    `& svg { color: green }` is wrong — set color on the container
+ *    and let currentColor inherit.
+ *
+ * 2. Don't use !important — it breaks the cascade.
+ *
+ * 3. Don't launder functional color tokens through @utility.
+ *    `@utility text-status-success { color: var(--color-status-active) }`
+ *    turns a functional color into a reusable className, which crosses
+ *    back from Presentation into Structure. Functional tokens belong
+ *    in scoped selectors like `.badge[data-status="paid"]`, not in
+ *    utilities that can spread via @apply or className.
+ *
+ * 4. Don't set color on descendants inside data-attribute selectors.
+ *    `.card[data-status="error"] .icon { color: red }` is wrong —
+ *    set color on the container and let children inherit via currentColor.
+ *
+ * 5. Don't animate layout properties (width, height, margin, padding,
+ *    top/right/bottom/left). These trigger reflow on every frame.
+ *    Use transform (scaleY, translateY) or opacity instead.
+ */
+interface StyleLintOptions {
+    /** Element selectors to allow (e.g. in resets).
+     *  @default ["html", "body"] */
+    ignoreTypes?: string[];
+    /** CSS custom property prefixes that must not appear inside @utility blocks.
+     *  e.g. ["--color-status-", "--color-danger"]
+     *  Any var() referencing these inside @utility is a lint error. */
+    functionalTokens?: string[];
+    /** Glob patterns for files to lint.
+     *  @default ["src/**\/*.css"] */
+    files?: string[];
+}
+declare function createStyleLint(options?: StyleLintOptions): {
+    files: string[];
+    plugins: unknown[];
+    rules: Record<string, unknown>;
+};
+
+export { type StyleLintOptions, createStyleLint };

package/dist/stylelint.js

@@ -0,0 +1,92 @@
+// src/stylelint.ts
+var pluginRuleName = "stablekit/no-functional-in-utility";
+var descendantColorRuleName = "stablekit/no-descendant-color-in-state";
+function createFunctionalTokenPlugin(prefixes) {
+  const rule = (enabled) => {
+    return (root, result) => {
+      if (!enabled) return;
+      root.walkAtRules("utility", (atRule) => {
+        atRule.walkDecls((decl) => {
+          for (const prefix of prefixes) {
+            if (decl.value.includes(prefix)) {
+              result.warn(
+                `Functional token "${prefix}*" inside @utility. Functional colors belong in scoped selectors (e.g. .badge[data-status="paid"]), not reusable utilities.`,
+                { node: decl }
+              );
+            }
+          }
+        });
+      });
+    };
+  };
+  return {
+    ruleName: pluginRuleName,
+    rule
+  };
+}
+function createDescendantColorPlugin() {
+  const dataAttrWithDescendant = /\[data-[^\]]+\]\s+[.#\w]/;
+  const colorApplyPattern = /\btext-(?!xs|sm|base|lg|xl|2xl|3xl|4xl|5xl|6xl|7xl|8xl|9xl|left|right|center|justify|wrap|nowrap|ellipsis|clip|truncate)\w/;
+  const message = `Setting color on a descendant inside a data-attribute selector. Set color on the [data-*] container and let children inherit via currentColor.`;
+  const rule = (enabled) => {
+    return (root, result) => {
+      if (!enabled) return;
+      root.walkRules((ruleNode) => {
+        if (!dataAttrWithDescendant.test(ruleNode.selector)) return;
+        ruleNode.walkDecls("color", (decl) => {
+          result.warn(message, { node: decl });
+        });
+        ruleNode.walkAtRules("apply", (atRule) => {
+          if (colorApplyPattern.test(atRule.params)) {
+            result.warn(message, { node: atRule });
+          }
+        });
+      });
+    };
+  };
+  return {
+    ruleName: descendantColorRuleName,
+    rule
+  };
+}
+function createStyleLint(options = {}) {
+  const {
+    ignoreTypes = ["html", "body"],
+    functionalTokens = [],
+    files = ["src/**/*.css"]
+  } = options;
+  const plugins = [createDescendantColorPlugin()];
+  if (functionalTokens.length > 0) {
+    plugins.push(createFunctionalTokenPlugin(functionalTokens));
+  }
+  const rules = {
+    // Ban element selectors — use classes and data-attributes instead.
+    "selector-max-type": [
+      0,
+      {
+        ignoreTypes
+      }
+    ],
+    // !important breaks the cascade and fights the architecture.
+    "declaration-no-important": true,
+    // Ban color on descendants inside data-attribute selectors.
+    [descendantColorRuleName]: true,
+    // Ban animating layout properties — causes reflow on every frame.
+    // Use transform (scaleY, translateY) or opacity instead.
+    "declaration-property-value-disallowed-list": [
+      {
+        "transition": [/\b(width|height|max-height|min-height|max-width|min-width|margin|padding|top|right|bottom|left)\b/],
+        "transition-property": [/\b(width|height|max-height|min-height|max-width|min-width|margin|padding|top|right|bottom|left)\b/],
+        "animation-name": []
+      },
+      { message: "Animating layout properties causes reflow. Use transform or opacity instead." }
+    ]
+  };
+  if (functionalTokens.length > 0) {
+    rules[pluginRuleName] = true;
+  }
+  return { files, plugins, rules };
+}
+export {
+  createStyleLint
+};

package/dist/styles.css

@@ -0,0 +1,178 @@
+/* stablekit — layout stability toolkit for React
+ *
+ * CSS class prefix: sk-
+ * All animations use CSS custom properties for themability.
+ * Styles are auto-injected at import time (opt-out via meta tag).
+ */
+
+/* ── LayoutGroup / LayoutView ──────────────────────────────────────────────── */
+
+/* All children overlap in the same grid cell.
+   Grid auto-sizes to the largest child.
+   Block-level groups use flex-column so content stretches to fill
+   the reserved width. Inline groups (data-inline) skip this — their
+   children are inline content that shouldn't be forced vertical. */
+.sk-layout-group {
+  display: grid;
+}
+.sk-layout-group[data-inline] {
+  display: inline-grid;
+}
+.sk-layout-group > * {
+  grid-area: 1 / 1;
+}
+.sk-layout-group:not([data-inline]) > * {
+  display: flex;
+  flex-direction: column;
+}
+/* Inline groups: children inherit the parent's inline flow.
+   Without this, grid items default to block and stack content. */
+.sk-layout-group[data-inline] > * {
+  display: inline;
+}
+
+/* Inactive LayoutView hiding — CSS-driven via data-state attribute.
+   LayoutView sets data-state="active"|"inactive" so consumers can
+   override transitions on .sk-layout-view without specificity fights.
+   [inert] handles accessibility (non-focusable, non-interactive). */
+.sk-layout-view[data-state="inactive"] {
+  opacity: 0;
+  visibility: hidden;
+}
+
+/* ── SizeRatchet ───────────────────────────────────────────────────────────── */
+
+/* contain isolates internal reflow from ancestors. */
+.sk-size-ratchet {
+  contain: layout style;
+}
+
+/* ── Shimmer / Skeleton ────────────────────────────────────────────────────── */
+
+.sk-skeleton-grid {
+  display: grid;
+  gap: var(--sk-skeleton-gap, 0.75rem);
+  contain: layout style;
+}
+
+.sk-skeleton-bone {
+  display: flex;
+  flex-direction: column;
+  gap: var(--sk-skeleton-bone-gap, 0.125rem);
+  padding: var(--sk-skeleton-bone-padding, 0.375rem 0.5rem);
+}
+
+.sk-shimmer-line {
+  height: 1lh;
+  border-radius: var(--sk-shimmer-radius, 0.125rem);
+  background: linear-gradient(
+    90deg,
+    var(--sk-shimmer-color, #e5e7eb) 25%,
+    var(--sk-shimmer-highlight, #f3f4f6) 50%,
+    var(--sk-shimmer-color, #e5e7eb) 75%
+  );
+  background-size: 200% 100%;
+  animation: sk-shimmer var(--sk-shimmer-duration, 1.5s) ease-in-out infinite;
+}
+
+/* Inert ghost inside a shimmer-line — sizes the shimmer to match
+   content width exactly. Invisible and non-interactive via [inert]. */
+.sk-shimmer-line > [inert] {
+  visibility: hidden;
+}
+
+@keyframes sk-shimmer {
+  0% { background-position: 200% 0; }
+  100% { background-position: -200% 0; }
+}
+
+/* ── MediaSkeleton ─────────────────────────────────────────────────────────── */
+
+/* Loading-aware media container.
+   Reserves space via aspect-ratio (set inline by the component).
+   Child constraints enforced via React.cloneElement inline styles. */
+.sk-media {
+  overflow: hidden;
+}
+.sk-media-shimmer {
+  position: absolute;
+  inset: 0;
+  border-radius: var(--sk-shimmer-radius, 0.125rem);
+  background: linear-gradient(
+    90deg,
+    var(--sk-shimmer-color, #e5e7eb) 25%,
+    var(--sk-shimmer-highlight, #f3f4f6) 50%,
+    var(--sk-shimmer-color, #e5e7eb) 75%
+  );
+  background-size: 200% 100%;
+  animation: sk-shimmer var(--sk-shimmer-duration, 1.5s) ease-in-out infinite;
+  transition: opacity var(--sk-loading-exit-duration, 400ms) var(--sk-ease-decelerate);
+}
+
+/* ── Shared easing ────────────────────────────────────────────────────────── */
+
+/* Decelerate: fast start, gentle finish — for elements entering view. */
+/* Standard: balanced ease — for general-purpose transitions. */
+/* Accelerate: gentle start, fast finish — for elements leaving view. */
+:root {
+  --sk-ease-decelerate: cubic-bezier(0.05, 0.7, 0.1, 1.0);
+  --sk-ease-standard: cubic-bezier(0.4, 0, 0.2, 1);
+  --sk-ease-accelerate: cubic-bezier(0.4, 0, 1, 1);
+}
+
+/* ── FadeTransition ────────────────────────────────────────────────────────── */
+
+.sk-fade {
+  --sk-fade-duration: 400ms;
+}
+
+.sk-fade-entering {
+  animation: sk-emerge var(--sk-fade-duration) var(--sk-ease-decelerate) forwards;
+}
+
+.sk-fade-exiting {
+  animation: sk-collapse var(--sk-fade-duration) var(--sk-ease-accelerate) forwards;
+}
+
+@keyframes sk-emerge {
+  from {
+    opacity: 0;
+    transform: translateY(var(--sk-fade-offset-y, -12px)) scale(var(--sk-fade-offset-scale, 0.98));
+  }
+  to {
+    opacity: 1;
+    transform: translateY(0) scale(1);
+  }
+}
+
+@keyframes sk-collapse {
+  from { opacity: 1; transform: scaleY(1); transform-origin: top; }
+  to   { opacity: 0; transform: scaleY(0); transform-origin: top; }
+}
+
+/* ── Loading layers ────────────────────────────────────────────────────────── */
+
+/* Shared by shimmer and content layers inside skeleton components.
+   Both layers permanently occupy the same grid cell; only opacity
+   and interactivity change. CSS transitions handle the crossfade. */
+.sk-loading-layer {
+  grid-area: 1 / 1;
+  transition: opacity var(--sk-loading-exit-duration, 400ms) var(--sk-ease-decelerate);
+}
+
+/* ── Reduced motion ────────────────────────────────────────────────────────── */
+
+/* Disables all animations — shimmer, fade, and loading exit.
+   Layout changes still happen instantly so functionality is preserved. */
+@media (prefers-reduced-motion: reduce) {
+  .sk-fade-entering,
+  .sk-fade-exiting,
+  .sk-shimmer-line,
+  .sk-media-shimmer {
+    animation-duration: 0s !important;
+  }
+  .sk-loading-layer,
+  .sk-media-shimmer {
+    transition-duration: 0s !important;
+  }
+}