css-is-awesome 1.1.0

package/scss/_icons.scss

@@ -0,0 +1,475 @@
+// ============================================================================
+// ICONS — Two Separate Systems (SVG + Font Awesome)
+// ============================================================================
+// This module ships two independent icon APIs. Use whichever fits — or both.
+// They do NOT depend on each other.
+//
+// ----------------------------------------------------------------------------
+// 1. SVG icons (folder-based, zero registration)
+// ----------------------------------------------------------------------------
+//   `svg($name)`       — inline icon rendered via CSS mask + currentColor.
+//                        Single-color, reskins automatically with `color:`.
+//   `svg-bg($name)`    — icon as `background-image`. Multi-color SVGs stay
+//                        multi-color (no mask, no tint).
+//   `svg-text($name)`  — icon + label in one element via ::before / ::after,
+//                        with gap + before/after positioning.
+//
+// ----------------------------------------------------------------------------
+// 2. Font Awesome icons (font-based)
+// ----------------------------------------------------------------------------
+//   `fa-load`          — @font-face declarations (call once if self-hosting).
+//   `fa($name)`        — raw ::before/::after content (FA glyph + font).
+//   `fa-icon($name)`   — standalone FA icon element.
+//   `fa-text($name)`   — FA icon + label, same gap/position API as svg-text.
+//   `fa-spin($name)`   — FA icon with a built-in spinner animation.
+//
+// ----------------------------------------------------------------------------
+// Config points (all defined in `scss/theme/_icons.scss` and re-exported
+// from `scss/theme/_index.scss` as `t.$theme-*`):
+// ----------------------------------------------------------------------------
+//   $theme-icon-path        — URL where SVGs live. Default: '/icons'.
+//                             Themes can override to ship their own pack.
+//   $theme-icon-size        — default icon dimension. Default: 24px.
+//   $theme-icon-svg-alias   — map of semantic-name → file-name remaps,
+//                             e.g. (delete: 'trash', close: 'x').
+//   $theme-fa-path          — URL where FA woff2 files live. Default:
+//                             '/webfonts'.
+//   $theme-fa-style         — default FA family (solid|regular|light|
+//                             thin|brands|duotone). Default: solid.
+//   $theme-fa-pro           — flip to `true` if you've licensed Font
+//                             Awesome 6 Pro. Adds Light / Thin / Duotone
+//                             to fa-load and switches Solid / Regular to
+//                             the "Font Awesome 6 Pro" family. Default:
+//                             false (Free).
+//   $theme-icon-fa-map      — map of semantic-name → FA unicode codepoint.
+//
+// ----------------------------------------------------------------------------
+// currentColor behavior
+// ----------------------------------------------------------------------------
+// `svg` and `svg-text` paint via CSS mask + `background: currentColor`, so
+// the icon inherits whatever `color:` is set on the element (or an ancestor).
+// Set `color: red;` on the parent and the icon turns red. No extra CSS.
+//
+// `svg-bg` does NOT recolor — it renders the source SVG as-is. Use it when
+// the SVG has multiple baked-in colors you want to preserve.
+//
+// ----------------------------------------------------------------------------
+// Adding icons
+// ----------------------------------------------------------------------------
+// Drop an SVG into the `$theme-icon-path` folder. Filename becomes the name:
+// `arrow-right.svg` → `@include m.svg(arrow-right);`. See the authoring
+// guide at `public/icons/README.md` for sizing, coloring, aliases, and
+// per-theme icon packs.
+// ============================================================================
+
+@use 'sass:map';
+@use 'sass:list';
+@use './theme' as t;
+
+// ============================================================================
+// SVG ICONS
+// ============================================================================
+// PACK-BASED: glyphs live at $theme-icon-path/$theme-icon-pack/<name>.svg.
+// Default pack is `core` (vendored from Lucide). Drop additional SVGs into
+// /icons/<pack>/ to add a new pack, or into the same `core` folder to add
+// to the default pack.
+//
+// How `m.svg(name)` resolves at runtime:
+//
+//   mask: var(--cia-icon-<name>, url('<core-pack-path>/<name>.svg'));
+//
+//   1. If a theme declares `--cia-icon-<name>: url(...)` on `:root`, the
+//      browser uses that override URL — that file lives at
+//      /themes/<theme-name>/icons/<pack>/<name>.svg by convention.
+//   2. Else the browser falls back to the bundled core-pack URL.
+//   3. If neither resolves, the browser 404s (graceful — the host element
+//      stays sized but renders empty).
+//
+// At compile time, an alias map ($theme-icon-svg-alias) lets call sites
+// use semantic names (close, delete) that resolve to a different on-disk
+// filename (x, trash). Aliases run BEFORE the override lookup so theme
+// overrides key off the canonical filename, not the alias.
+//
+// To add icons: drop the .svg file in /icons/<pack>/. Done.
+// To override an icon for one theme: drop a replacement at
+// /themes/<theme>/icons/<pack>/<name>.svg AND declare the override
+// custom property in that theme's theme.css. See CONTRACT.md →
+// "Icons contract" for the full mechanism.
+// ============================================================================
+
+// ----------------------------------------------------------------------------
+// _svg-file($name) — private helper
+// Resolves a semantic name to an actual .svg filename by checking the
+// alias map. If the name isn't aliased, the name itself is returned.
+//   _svg-file(delete)  → 'trash'      (via alias map)
+//   _svg-file(arrow)   → arrow        (pass-through)
+// ----------------------------------------------------------------------------
+@function _svg-file($name) {
+  $alias: map.get(t.$theme-icon-svg-alias, $name);
+  @if $alias {
+    @return $alias;
+  }
+  @return $name;
+}
+
+// ----------------------------------------------------------------------------
+// _svg-url($name) — private helper
+// Returns the unquoted CSS value used in mask / background. Emits a
+// `var(--cia-icon-<file>, url('<base>/<file>.svg'))` so themes can
+// override one glyph at a time by declaring the custom property without
+// touching the rest of the pack.
+// ----------------------------------------------------------------------------
+@function _svg-url($name) {
+  $file: _svg-file($name);
+  $base: '#{t.$theme-icon-path}/#{t.$theme-icon-pack}';
+  @return var(
+    --cia-icon-#{$file},
+    url('#{$base}/#{$file}.svg')
+  );
+}
+
+// ----------------------------------------------------------------------------
+// @mixin svg($name, $size, $color)
+// Renders a single-color SVG as an inline element using CSS mask +
+// currentColor. The icon automatically reskins with the parent's `color`.
+// Use this for icons that should tint with text color.
+//
+// Params:
+//   $name    — icon name (matches `<name>.svg` in $theme-icon-path)
+//   $size    — icon width/height (default: t.$theme-icon-size)
+//   $color   — icon color (default: currentColor)
+//
+// Example:
+//   .btn-close { @include m.svg(close); color: var(--color-danger); }
+// ----------------------------------------------------------------------------
+@mixin svg(
+  $name,
+  $size: t.$theme-icon-size,
+  $color: currentColor
+) {
+  $url: _svg-url($name);
+
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: $size;
+  height: $size;
+  color: $color;
+
+  &::before {
+    content: '';
+    display: block;
+    width: 100%;
+    height: 100%;
+    background: currentColor;
+    mask: $url center / contain no-repeat;
+    -webkit-mask: $url center / contain no-repeat;
+  }
+}
+
+// ----------------------------------------------------------------------------
+// @mixin svg-bg($name, $size)
+// Renders an SVG as a plain `background-image`. No mask, no recoloring —
+// multi-color source SVGs render with their original palette. Use this for
+// brand marks, illustrations, or any icon whose colors must stay baked in.
+//
+// Params:
+//   $name  — icon name (matches `<name>.svg` in $theme-icon-path)
+//   $size  — icon width/height (default: t.$theme-icon-size)
+//
+// Example:
+//   .logo { @include m.svg-bg(brand-mark, 48px); }
+// ----------------------------------------------------------------------------
+@mixin svg-bg(
+  $name,
+  $size: t.$theme-icon-size
+) {
+  $url: _svg-url($name);
+
+  display: inline-block;
+  width: $size;
+  height: $size;
+  background: $url center / contain no-repeat;
+}
+
+// ----------------------------------------------------------------------------
+// @mixin svg-text($name, $size, $gap, $position)
+// Pairs an SVG icon with its parent's text content in a single flex row.
+// The icon is drawn via ::before (default) or ::after, tinted by
+// currentColor, and separated from the text by $gap.
+//
+// Params:
+//   $name      — icon name
+//   $size      — icon dimension (default: 1em, scales with font-size)
+//   $gap       — space between icon and text (default: 0.5em)
+//   $position  — `before` or `after` (default: before)
+//
+// Example:
+//   .btn-save { @include m.svg-text(check, 1em, 0.5em, before); }
+// ----------------------------------------------------------------------------
+@mixin svg-text(
+  $name,
+  $size: 1em,
+  $gap: 0.5em,
+  $position: before
+) {
+  $url: _svg-url($name);
+
+  display: inline-flex;
+  align-items: center;
+  gap: $gap;
+
+  @if $position == after {
+    flex-direction: row-reverse;
+  }
+
+  &::#{$position} {
+    content: '';
+    flex-shrink: 0;
+    width: $size;
+    height: $size;
+    background: currentColor;
+    mask: $url center / contain no-repeat;
+    -webkit-mask: $url center / contain no-repeat;
+  }
+}
+
+// ============================================================================
+// FONT AWESOME ICONS
+// ============================================================================
+// Opt-in. Only use if your project is already on Font Awesome.
+// Configure $theme-fa-path, $theme-icon-fa-map, and (for licensed users)
+// $theme-fa-pro in scss/theme/_icons.scss.
+// ============================================================================
+
+// FA family config — maps a style name to (font-family, font-weight).
+// Two maps: Free ships Solid + Regular + Brands; Pro adds Light + Thin +
+// Duotone and renames Solid/Regular to the "Font Awesome 6 Pro" family.
+// $_fa-styles is selected based on t.$theme-fa-pro.
+$_fa-styles-free: (
+  solid:   ('Font Awesome 6 Free', 900),
+  regular: ('Font Awesome 6 Free', 400),
+  brands:  ('Font Awesome 6 Brands', 400),
+);
+
+$_fa-styles-pro: (
+  solid:   ('Font Awesome 6 Pro', 900),
+  regular: ('Font Awesome 6 Pro', 400),
+  light:   ('Font Awesome 6 Pro', 300),
+  thin:    ('Font Awesome 6 Pro', 100),
+  brands:  ('Font Awesome 6 Brands', 400),
+  duotone: ('Font Awesome 6 Duotone', 900),
+);
+
+@function _fa-styles($pro) {
+  @if $pro { @return $_fa-styles-pro; }
+  @return $_fa-styles-free;
+}
+
+@function _fa-family($pro) {
+  @if $pro { @return 'Font Awesome 6 Pro'; }
+  @return 'Font Awesome 6 Free';
+}
+
+$_fa-styles: _fa-styles(t.$theme-fa-pro);
+
+// ----------------------------------------------------------------------------
+// @mixin fa-load($pro)
+// Emits @font-face rules for self-hosted Font Awesome 6.
+// Call this exactly once (e.g. in main.scss) if you ship FA woff2 files.
+// Skip this mixin entirely if you load FA via their CDN/kit.
+//
+// Free (default):  Solid + Regular + Brands.
+// Pro:             also Light + Thin + Duotone, with Solid / Regular
+//                  switched to the "Font Awesome 6 Pro" family.
+//
+// To turn Pro on, set the global flag once and `fa-load` plus `fa()` both
+// follow:
+//
+//   @use 'css-is-awesome/scss/theme/icons' with ($fa-pro: true);
+//   @use 'css-is-awesome/scss/main';
+//   :root { @include m.fa-load; }
+//
+// The $pro parameter here is an escape hatch — useful if you only want to
+// flip the @font-face emission (e.g. hybrid setups). Most projects should
+// set the global so fa-load and fa() agree on the family map.
+//
+// Drop the woff2 files for the weights you ship at $theme-fa-path; missing
+// files won't error, they just won't render until you add them.
+// ----------------------------------------------------------------------------
+@mixin fa-load($pro: t.$theme-fa-pro) {
+  $family: _fa-family($pro);
+
+  @font-face {
+    font-family: $family;
+    font-style: normal;
+    font-weight: 400;
+    font-display: block;
+    src: url('#{t.$theme-fa-path}/fa-regular-400.woff2') format('woff2');
+  }
+  @font-face {
+    font-family: $family;
+    font-style: normal;
+    font-weight: 900;
+    font-display: block;
+    src: url('#{t.$theme-fa-path}/fa-solid-900.woff2') format('woff2');
+  }
+  @font-face {
+    font-family: 'Font Awesome 6 Brands';
+    font-style: normal;
+    font-weight: 400;
+    font-display: block;
+    src: url('#{t.$theme-fa-path}/fa-brands-400.woff2') format('woff2');
+  }
+
+  @if $pro {
+    @font-face {
+      font-family: 'Font Awesome 6 Pro';
+      font-style: normal;
+      font-weight: 300;
+      font-display: block;
+      src: url('#{t.$theme-fa-path}/fa-light-300.woff2') format('woff2');
+    }
+    @font-face {
+      font-family: 'Font Awesome 6 Pro';
+      font-style: normal;
+      font-weight: 100;
+      font-display: block;
+      src: url('#{t.$theme-fa-path}/fa-thin-100.woff2') format('woff2');
+    }
+    @font-face {
+      font-family: 'Font Awesome 6 Duotone';
+      font-style: normal;
+      font-weight: 900;
+      font-display: block;
+      src: url('#{t.$theme-fa-path}/fa-duotone-900.woff2') format('woff2');
+    }
+  }
+}
+
+// ----------------------------------------------------------------------------
+// @mixin fa($name, $style, $size)
+// Low-level primitive — emits the font-family/weight/content bundle for a
+// Font Awesome glyph. MUST be placed inside a ::before or ::after rule
+// because it sets `content:`. Most of the time you want `fa-icon` or
+// `fa-text` instead.
+//
+// Params:
+//   $name   — icon name from $theme-icon-fa-map, or a raw unicode string
+//   $style  — solid|regular|light|thin|brands (default: t.$theme-fa-style)
+//   $size   — optional font-size override
+//
+// Example:
+//   .alert::before { @include m.fa(warning, solid, 1.25em); }
+// ----------------------------------------------------------------------------
+@mixin fa(
+  $name,
+  $style: t.$theme-fa-style,
+  $size: null
+) {
+  $code: map.get(t.$theme-icon-fa-map, $name) or $name;
+  $config: map.get($_fa-styles, $style);
+
+  font-family: list.nth($config, 1);
+  font-weight: list.nth($config, 2);
+  font-style: normal;
+  line-height: 1;
+  content: $code;
+  -webkit-font-smoothing: antialiased;
+  -moz-osx-font-smoothing: grayscale;
+
+  @if $size { font-size: $size; }
+}
+
+// ----------------------------------------------------------------------------
+// @mixin fa-icon($name, $size, $style, $color)
+// Standalone Font Awesome icon — sizes the host element, renders the glyph
+// in ::before, and inherits currentColor by default. Counterpart to `svg`.
+//
+// Params:
+//   $name   — icon name (from $theme-icon-fa-map)
+//   $size   — icon width/height (default: t.$theme-icon-size)
+//   $style  — solid|regular|light|thin|brands (default: t.$theme-fa-style)
+//   $color  — icon color (default: currentColor)
+//
+// Example:
+//   .icon-search { @include m.fa-icon(search); }
+// ----------------------------------------------------------------------------
+@mixin fa-icon(
+  $name,
+  $size: t.$theme-icon-size,
+  $style: t.$theme-fa-style,
+  $color: currentColor
+) {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: $size;
+  height: $size;
+  color: $color;
+
+  &::before {
+    @include fa($name, $style, $size);
+  }
+}
+
+// ----------------------------------------------------------------------------
+// @mixin fa-text($name, $size, $gap, $style, $position)
+// Font Awesome icon + text label in a flex row. Mirrors the svg-text API.
+//
+// Params:
+//   $name      — icon name
+//   $size      — icon dimension (default: 1em)
+//   $gap       — space between icon and text (default: 0.5em)
+//   $style     — FA family (default: t.$theme-fa-style)
+//   $position  — `before` or `after` (default: before)
+//
+// Example:
+//   .btn-download { @include m.fa-text(download); }
+// ----------------------------------------------------------------------------
+@mixin fa-text(
+  $name,
+  $size: 1em,
+  $gap: 0.5em,
+  $style: t.$theme-fa-style,
+  $position: before
+) {
+  display: inline-flex;
+  align-items: center;
+  gap: $gap;
+
+  @if $position == after {
+    flex-direction: row-reverse;
+  }
+
+  &::#{$position} {
+    @include fa($name, $style, $size);
+  }
+}
+
+// ----------------------------------------------------------------------------
+// @mixin fa-spin($name, $size, $style)
+// Font Awesome icon with a built-in 1s linear infinite rotation. Use for
+// loading spinners. Injects an @keyframes `fa-spin` at the root once.
+//
+// Params:
+//   $name   — icon name (typically `spinner` or `refresh`)
+//   $size   — icon dimension (default: t.$theme-icon-size)
+//   $style  — FA family (default: t.$theme-fa-style)
+//
+// Example:
+//   .loader { @include m.fa-spin(spinner); }
+// ----------------------------------------------------------------------------
+@mixin fa-spin($name, $size: t.$theme-icon-size, $style: t.$theme-fa-style) {
+  @include fa-icon($name, $size, $style);
+
+  &::before {
+    animation: fa-spin 1s linear infinite;
+  }
+
+  @at-root {
+    @keyframes fa-spin {
+      to { transform: rotate(360deg); }
+    }
+  }
+}

package/scss/_index.scss

@@ -0,0 +1,17 @@
+// ============================================================================
+// INDEX - Full Barrel (authoring API + global animation utilities)
+// ============================================================================
+// Kitchen-sink barrel: the zero-emit authoring API (defined in `api.scss`)
+// PLUS the global animation utility classes + keyframes + reduced-motion
+// safety net, which DO emit CSS.
+//
+// For a component-safe, ZERO-EMIT import (the common case, safe inside a
+// `.module.scss`), use `css-is-awesome/api` instead — see `api.scss`.
+//
+// The authoring surface (mixins/functions/token maps) is defined ONCE in
+// `api.scss`; this file only adds the emitting utilities on top, so the two
+// barrels can never drift.
+// ============================================================================
+
+@forward 'api';
+@forward './animations-utilities';  // Keyframes + .cia-anim-* + global reduced-motion safety net