feat(scroll): add scroll-driven animation utilities (#41)

auswm85 · web-flow · commit 9f4751e53476 · 2026-01-31T18:39:13.000-06:00
diff --git a/apps/docs/src/components/layout/BaseLayout.astro b/apps/docs/src/components/layout/BaseLayout.astro
@@ -63,6 +63,7 @@ const isHomePage = Astro.url.pathname === '/' || Astro.url.pathname === '';
 		<link rel="preload" href={`${base}/fonts/jetbrains-mono-latin-400-normal.woff2`} as="font" type="font/woff2" crossorigin />
 	</head>
 	<body>
+		<div s-scroll-progress aria-hidden="true"></div>
 		<slot />
 		{!isThemePage && !isHomePage && <ThemeCustomizer />}
 	</body>
diff --git a/apps/docs/src/styles/docs.css b/apps/docs/src/styles/docs.css
@@ -61,7 +61,7 @@ html {
 
 .docs-header {
 	position: sticky;
-	top: 0;
+	top: 3px; /* Make room for scroll progress bar */
 	z-index: 100;
 	height: var(--docs-header-height);
 	display: flex;
diff --git a/apps/docs/tsconfig.json b/apps/docs/tsconfig.json
@@ -2,8 +2,6 @@
   "extends": "astro/tsconfigs/strict",
   "compilerOptions": {
     "strictNullChecks": true,
-    "plugins": [
-      { "name": "@astrojs/ts-plugin" }
-    ]
+    "plugins": [{ "name": "@astrojs/ts-plugin" }]
   }
 }
diff --git a/packages/core/scripts/build.ts b/packages/core/scripts/build.ts
@@ -103,6 +103,7 @@ function buildIndividualLayers(): void {
 		{ name: 'flex', path: 'utils/flex.css' },
 		{ name: 'typography', path: 'utils/typography.css' },
 		{ name: 'visibility', path: 'utils/visibility.css' },
+		{ name: 'scroll', path: 'utils/scroll.css' },
 	];
 
 	// Create subdirectories
diff --git a/packages/core/src/components/card.css b/packages/core/src/components/card.css
@@ -3,11 +3,16 @@
  *
  * Flexible card component with header, body, footer sections.
  * Uses semantic attribute selectors and supports container queries.
+ * Progressively enhanced with @scope for proper isolation of nested cards.
  *
  * Usage:
  *   <article s-card>Basic card content</article>
  *   <article s-card s-surface="raised">Elevated card</article>
  *   <article s-card s-interactive>Clickable card</article>
+ *
+ * Browser Support:
+ *   - All browsers: Standard attribute selectors
+ *   - Chrome 118+, Safari 17.4+: @scope for nested card isolation
  */
 
 /* Base card - zero specificity for easy overrides */
@@ -85,6 +90,13 @@
   color: var(--s-text-secondary);
 }
 
+/* Card actions (base fallback for browsers without @scope) */
+[s-card-actions] {
+  display: flex;
+  gap: var(--s-space-2);
+  margin-top: var(--s-space-4);
+}
+
 /* =============================================================================
    CARD VARIANTS
    ============================================================================= */
@@ -262,3 +274,46 @@
     }
   }
 }
+
+/* =============================================================================
+   CSS @SCOPE - Nested Card Isolation (Progressive Enhancement)
+
+   When cards are nested inside other cards, this ensures that parent card
+   styles (like borders and separators) don't bleed into child cards.
+   Uses "donut scope" to exclude nested [s-card] elements.
+   ============================================================================= */
+
+@supports (selector(:scope)) {
+  @scope ([s-card]) to ([s-card]) {
+    /**
+     * Scoped card sections - these styles only apply to direct card sections,
+     * not sections inside nested cards.
+     */
+
+    /* Header with bottom border - only for this card's header */
+    [s-card-header] {
+      border-bottom: 1px solid var(--_card-border, var(--s-border-muted));
+    }
+
+    /* Footer with top border - only for this card's footer */
+    [s-card-footer] {
+      border-top: 1px solid var(--_card-border, var(--s-border-muted));
+    }
+
+    /* Typography inherits from scoped card context */
+    [s-card-title] {
+      color: inherit;
+    }
+
+    [s-card-subtitle] {
+      color: var(--s-text-secondary);
+    }
+
+    /* Actions container scoped to this card */
+    [s-card-actions] {
+      display: flex;
+      gap: var(--s-space-2);
+      margin-top: var(--s-space-4);
+    }
+  }
+}
diff --git a/packages/core/src/components/input.css b/packages/core/src/components/input.css
@@ -98,6 +98,18 @@ textarea[s-input] {
   resize: vertical;
 }
 
+/* Auto-sizing textarea - grows with content */
+textarea[s-input][s-autosize] {
+  resize: none;
+
+  /* Progressive enhancement: field-sizing auto-grows with content */
+  @supports (field-sizing: content) {
+    field-sizing: content;
+    min-height: 3lh; /* Minimum 3 lines using line-height units */
+    max-height: 20lh; /* Maximum 20 lines before scrolling */
+  }
+}
+
 /* Select */
 select[s-input] {
   background-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='16' height='16' viewBox='0 0 24 24' fill='none' stroke='currentColor' stroke-width='2'%3E%3Cpath d='M6 9l6 6 6-6'/%3E%3C/svg%3E");
diff --git a/packages/core/src/components/modal.css b/packages/core/src/components/modal.css
@@ -61,49 +61,88 @@ dialog[s-modal]:not([open]) {
   color: var(--s-text-primary);
 }
 
-/* Open state animation */
+/* Open state animation - using @starting-style for cleaner entry animations */
 dialog[s-modal][open] {
-  animation: s-modal-scale-in var(--s-duration-200) var(--s-ease-out);
-}
-
-/* Focus visible state for keyboard navigation */
-dialog[s-modal]:focus-visible {
-  outline: 2px solid var(--s-focus-ring);
-  outline-offset: 2px;
+  opacity: 1;
+  transform: scale(1) translateY(0);
+  transition:
+    opacity var(--s-duration-200) var(--s-ease-out),
+    transform var(--s-duration-200) var(--s-ease-out),
+    overlay var(--s-duration-200) var(--s-ease-out) allow-discrete,
+    display var(--s-duration-200) var(--s-ease-out) allow-discrete;
 }
 
-@keyframes s-modal-scale-in {
-  from {
+/* Entry animation initial state - CSS @starting-style */
+@starting-style {
+  dialog[s-modal][open] {
     opacity: 0;
     transform: scale(0.95) translateY(-10px);
   }
-  to {
-    opacity: 1;
-    transform: scale(1) translateY(0);
+}
+
+/* Fallback for browsers without @starting-style (using transition-behavior as proxy test) */
+@supports not (transition-behavior: allow-discrete) {
+  dialog[s-modal][open] {
+    animation: s-modal-scale-in var(--s-duration-200) var(--s-ease-out);
+  }
+
+  @keyframes s-modal-scale-in {
+    from {
+      opacity: 0;
+      transform: scale(0.95) translateY(-10px);
+    }
+    to {
+      opacity: 1;
+      transform: scale(1) translateY(0);
+    }
   }
 }
 
+/* Focus visible state for keyboard navigation */
+dialog[s-modal]:focus-visible {
+  outline: 2px solid var(--s-focus-ring);
+  outline-offset: 2px;
+}
+
 /* =============================================================================
    BACKDROP STYLING
    ============================================================================= */
 
 dialog[s-modal]::backdrop {
   background: oklch(0 0 0 / 0.5);
   backdrop-filter: blur(4px);
-  animation: s-modal-backdrop-in var(--s-duration-200) var(--s-ease-out);
+  opacity: 1;
+  transition:
+    opacity var(--s-duration-200) var(--s-ease-out),
+    overlay var(--s-duration-200) var(--s-ease-out) allow-discrete,
+    display var(--s-duration-200) var(--s-ease-out) allow-discrete;
 
   /* RCS: adaptive backdrop - tinted with brand hue */
   @supports (color: oklch(from red l c h)) {
     background: oklch(from var(--s-primary-500) 0.1 0.02 h / 0.5);
   }
 }
 
-@keyframes s-modal-backdrop-in {
-  from {
+/* Backdrop entry animation */
+@starting-style {
+  dialog[s-modal]::backdrop {
     opacity: 0;
   }
-  to {
-    opacity: 1;
+}
+
+/* Fallback for browsers without @starting-style (using transition-behavior as proxy test) */
+@supports not (transition-behavior: allow-discrete) {
+  dialog[s-modal]::backdrop {
+    animation: s-modal-backdrop-in var(--s-duration-200) var(--s-ease-out);
+  }
+
+  @keyframes s-modal-backdrop-in {
+    from {
+      opacity: 0;
+    }
+    to {
+      opacity: 1;
+    }
   }
 }
 
@@ -262,6 +301,18 @@ dialog[s-modal][s-position="right"] {
    ACCESSIBILITY & HIGH CONTRAST
    ============================================================================= */
 
+/* Respect reduced motion preferences */
+@media (prefers-reduced-motion: reduce) {
+  dialog[s-modal][open] {
+    transition: none;
+    transform: none;
+  }
+
+  dialog[s-modal]::backdrop {
+    transition: none;
+  }
+}
+
 /* High contrast mode support */
 @media (forced-colors: active) {
   dialog[s-modal] {
diff --git a/packages/core/src/components/tooltip.css b/packages/core/src/components/tooltip.css
@@ -65,7 +65,8 @@
 
   /* RCS: tethered tinting - derive border from tooltip background */
   @supports (color: oklch(from red l c h)) {
-    border: 1px solid oklch(from var(--_tooltip-bg) max(calc(l - 0.1), 0.05) c h);
+    border: 1px solid
+      oklch(from var(--_tooltip-bg) max(calc(l - 0.1), 0.05) c h);
   }
 
   /* Typography */
@@ -74,7 +75,10 @@
   line-height: var(--s-leading-tight);
   text-align: center;
   text-wrap: balance;
-  min-width: min(100%, var(--_tooltip-max-width)); /* At least as wide as trigger, capped at max */
+  min-width: min(
+    100%,
+    var(--_tooltip-max-width)
+  ); /* At least as wide as trigger, capped at max */
   max-width: var(--_tooltip-max-width);
 
   /* Prevent tooltip from blocking interactions */
diff --git a/packages/core/src/index.css b/packages/core/src/index.css
@@ -33,3 +33,4 @@
 @import "./utils/spacing.css" layer(shift.utils);
 @import "./utils/flex.css" layer(shift.utils);
 @import "./utils/typography.css" layer(shift.utils);
+@import "./utils/scroll.css" layer(shift.utils);
diff --git a/packages/core/src/utils/scroll.css b/packages/core/src/utils/scroll.css

Original file line number	Diff line number	Diff line change
`@@ -2,8 +2,6 @@`
`2`	`2`	`"extends": "astro/tsconfigs/strict",`
`3`	`3`	`"compilerOptions": {`
`4`	`4`	`"strictNullChecks": true,`
`5`		`- "plugins": [`
`6`		`- { "name": "@astrojs/ts-plugin" }`
`7`		`- ]`
	`5`	`+ "plugins": [{ "name": "@astrojs/ts-plugin" }]`
`8`	`6`	`}`
`9`	`7`	`}`