@mezzanine-ui/system 0.16.0 → 1.0.0-beta.0

package/spacing/typings.d.ts

@@ -1 +1,82 @@
+/** @deprecated */
 export type SpacingLevel = number;
+/**
+ * Spacing primitive scales - 間距原始級距（對應 px 值）
+ */
+export type SpacingScale = 0 | 1 | 2 | 4 | 6 | 8 | 10 | 12 | 14 | 16 | 18 | 20 | 24 | 28 | 32 | 36 | 40 | 48 | 52 | 56 | 60 | 64 | 80 | 160 | 240 | 320 | 360 | 400 | 480 | 560 | 640 | 720 | 960 | 1140;
+/**
+ * Spacing primitives configuration
+ */
+export type SpacingPrimitives = Partial<Record<SpacingScale, string | number>>;
+/**
+ * Spacing semantic contexts - 語意化間距的使用情境
+ */
+export type SpacingContext = 'size' | 'gap' | 'padding';
+/**
+ * Spacing mode - 間距模式
+ */
+export type SpacingMode = 'default' | 'compact';
+/**
+ * Size categories - 尺寸分類
+ */
+export type SizeCategory = 'element' | 'container';
+/**
+ * Padding categories - 內邊距分類
+ */
+export type PaddingCategory = 'horizontal' | 'vertical';
+/**
+ * Element size tones - 元素尺寸調性
+ */
+export type ElementTone = 'hairline' | 'tiny' | 'tight' | 'compact' | 'slim' | 'narrow' | 'base' | 'base-fixed' | 'gentle' | 'relaxed' | 'airy' | 'roomy' | 'loose' | 'extra-wide' | 'extra-wide-condense' | 'expansive' | 'extra' | 'max';
+/**
+ * Container size tones - 容器尺寸調性
+ */
+export type ContainerTone = 'collapsed' | 'tiny' | 'tight' | 'slim' | 'narrow' | 'compact' | 'standard' | 'balanced' | 'broad' | 'wide' | 'expanded' | 'max';
+/**
+ * Gap tones - 間隙調性
+ */
+export type GapTone = 'none' | 'micro' | 'tiny' | 'tight' | 'compact' | 'base' | 'base-fixed' | 'comfortable' | 'roomy' | 'spacious' | 'relaxed' | 'airy' | 'generous' | 'breath' | 'wide';
+/**
+ * Horizontal padding tones - 水平內邊距調性
+ */
+export type HorizontalPaddingTone = 'none' | 'micro' | 'tiny' | 'tiny-fixed' | 'tight' | 'tight-fixed' | 'base' | 'base-fixed' | 'calm' | 'comfort' | 'comfort-fixed' | 'roomy' | 'spacious' | 'relaxed' | 'airy' | 'breath' | 'wide' | 'max';
+/**
+ * Vertical padding tones - 垂直內邊距調性
+ */
+export type VerticalPaddingTone = 'none' | 'micro' | 'tiny' | 'tight' | 'base' | 'calm' | 'comfort' | 'roomy' | 'spacious' | 'generous' | 'relaxed';
+/**
+ * Category 與對應 Tone 的映射型別
+ */
+export type SpacingToneMap = {
+    size: {
+        element: ElementTone;
+        container: ContainerTone;
+    };
+    gap: GapTone;
+    padding: {
+        horizontal: HorizontalPaddingTone;
+        vertical: VerticalPaddingTone;
+    };
+};
+/**
+ * 取得特定 context 的 tone 型別
+ * @example
+ * type GapT = SpacingToneFor<'gap'>; // GapTone
+ */
+export type SpacingToneFor<C extends SpacingContext> = SpacingToneMap[C] extends infer T ? T extends {
+    element: any;
+} ? never : T : never;
+/**
+ * 取得特定 context + category 的 tone 型別
+ * @example
+ * type EleTone = SpacingCategoryToneFor<'size', 'element'>; // ElementTone
+ */
+export type SpacingCategoryToneFor<C extends SpacingContext, Cat extends C extends 'size' ? SizeCategory : C extends 'padding' ? PaddingCategory : never> = C extends 'size' ? Cat extends SizeCategory ? SpacingToneMap['size'][Cat] : never : C extends 'padding' ? Cat extends PaddingCategory ? SpacingToneMap['padding'][Cat] : never : never;
+/**
+ * Semantic spacing 完整型別 - context + category + tone 組合
+ * @example
+ * const spacing1: SemanticSpacing = 'size-element-base';
+ * const spacing2: SemanticSpacing = 'gap-comfortable';
+ * const spacing3: SemanticSpacing = 'padding-horizontal-calm';
+ */
+export type SemanticSpacing = `size-element-${ElementTone}` | `size-container-${ContainerTone}` | `gap-${GapTone}` | `padding-horizontal-${HorizontalPaddingTone}` | `padding-vertical-${VerticalPaddingTone}`;

package/transition/_transition.scss

@@ -1,17 +1,33 @@
+@use 'sass:meta';
+@use 'sass:string';
 @use '../motion';
 
-@function enter($property, $duration: motion.duration(short), $delay: 0ms) {
-  @return $property $duration motion.easing(decelerated) $delay;
-}
+@function entrance($property, $duration: moderate, $delay: 0ms) {
+  $duration-value: if(
+    meta.type-of($duration) == number or string.index(meta.inspect($duration), 'calc') != null,
+    $duration,
+    motion.duration($duration)
+  );
 
-@function exit($property, $duration: motion.duration(shorter), $delay: 0ms) {
-  @return $property $duration motion.easing(accelerated) $delay;
+  @return $property $duration-value motion.easing(entrance) $delay;
 }
 
-@function emphasized($property, $duration: motion.duration(short), $delay: 0ms) {
-  @return $property $duration motion.easing(emphasized) $delay;
+@function exit($property, $duration: moderate, $delay: 0ms) {
+  $duration-value: if(
+    meta.type-of($duration) == number or string.index(meta.inspect($duration), 'calc') != null,
+    $duration,
+    motion.duration($duration)
+  );
+
+  @return $property $duration-value motion.easing(exit) $delay;
 }
 
-@function standard($property, $duration: motion.duration(short), $delay: 0ms) {
-  @return $property $duration motion.easing(standard) $delay;
+@function standard($property, $duration: moderate, $delay: 0ms) {
+  $duration-value: if(
+    meta.type-of($duration) == number or string.index(meta.inspect($duration), 'calc') != null,
+    $duration,
+    motion.duration($duration)
+  );
+
+  @return $property $duration-value motion.easing(standard) $delay;
 }

package/typography/_index.scss

@@ -1,2 +1,5 @@
 @forward './utils';
-@forward './typography';
+@forward './typography'; // @deprecated - will be removed in next major version
+@forward './primitives' as primitive-*;
+@forward './semantic' as semantic-*;
+@forward './sf-mono';

package/typography/_primitives.scss

@@ -0,0 +1,318 @@
+@use 'sass:meta';
+@use '../utils/list';
+@use '../utils/map';
+@use './utils' as typography-utils;
+
+// ==========================================
+// Font Family Primitives
+// ==========================================
+
+// 定義所有可用的 font-family 類型
+$primitive-font-family-types: (
+  pingfangtc,
+  notosans,
+  sfmono
+);
+
+// CSS 變數前綴
+$primitive-prefix: mzn-typography-primitive;
+
+// 預設 font-family 定義
+$default-font-families: (
+  pingfangtc: 'PingFang TC',
+  notosans: 'Noto Sans TC',
+  sfmono: 'SF Mono',
+);
+
+// ==========================================
+// Font Weight Primitives
+// ==========================================
+
+// 定義所有可用的 font-weight 類型
+$primitive-font-weight-types: (
+  regular,
+  medium,
+  semibold
+);
+
+// 預設 font-weight 定義
+$default-font-weights: (
+  regular: 400,
+  medium: 500,
+  semibold: 600,
+);
+
+// ==========================================
+// Font Size Primitives
+// ==========================================
+
+// 定義所有可用的 font-size 級距
+$primitive-font-size-scales: (24, 18, 16, 14, 12, 10);
+
+// 預設 font-size 定義
+$default-font-sizes: (
+  24: typography-utils.px-to-rem(24px),
+  18: typography-utils.px-to-rem(18px),
+  16: typography-utils.px-to-rem(16px),
+  14: typography-utils.px-to-rem(14px),
+  12: typography-utils.px-to-rem(12px),
+  10: typography-utils.px-to-rem(10px),
+);
+
+// ==========================================
+// Line Height Primitives
+// ==========================================
+
+// 定義所有可用的 line-height 類型
+$primitive-line-height-types: (
+  h1,
+  h2,
+  h3,
+  body,
+  caption,
+  annotation,
+  functional
+);
+
+// 預設 line-height 定義
+$default-line-heights: (
+  h1: 28px,
+  h2: 24px,
+  h3: 22px,
+  body: 20px,
+  caption: 16px,
+  annotation: 14px,
+  functional: 16px,
+);
+
+// ==========================================
+// Letter Spacing Primitives
+// ==========================================
+
+// 定義所有可用的 letter-spacing 類型
+$primitive-letter-spacing-types: (
+  0
+);
+
+// 預設 letter-spacing 定義
+$default-letter-spacings: (
+  0: 0em,
+);
+
+// ==========================================
+// Validation Functions
+// ==========================================
+
+@function is-font-family-type-valid($type) {
+  @return list.includes($primitive-font-family-types, $type);
+}
+
+@function is-font-weight-type-valid($type) {
+  @return list.includes($primitive-font-weight-types, $type);
+}
+
+@function is-font-size-scale-valid($scale) {
+  @return list.includes($primitive-font-size-scales, $scale);
+}
+
+@function is-line-height-type-valid($type) {
+  @return list.includes($primitive-line-height-types, $type);
+}
+
+@function is-letter-spacing-type-valid($type) {
+  @return list.includes($primitive-letter-spacing-types, $type);
+}
+
+// ==========================================
+// CSS Variable Functions
+// ==========================================
+
+// Get font-family CSS variable
+@function font-family-variable($type, $fallback: null) {
+  @if not is-font-family-type-valid($type) {
+    @error 'Invalid font-family type #{$type}. Please choose one of #{$primitive-font-family-types}';
+  }
+
+  $varname: --#{$primitive-prefix}-font-family-#{$type};
+
+  @if not $fallback {
+    @return var(#{$varname});
+  }
+
+  @return var(#{$varname}, $fallback);
+}
+
+// Get font-weight CSS variable
+@function font-weight-variable($type, $fallback: null) {
+  @if not is-font-weight-type-valid($type) {
+    @error 'Invalid font-weight type #{$type}. Please choose one of #{$primitive-font-weight-types}';
+  }
+
+  $varname: --#{$primitive-prefix}-font-weight-#{$type};
+
+  @if not $fallback {
+    @return var(#{$varname});
+  }
+
+  @return var(#{$varname}, $fallback);
+}
+
+// Get font-size CSS variable
+@function font-size-variable($scale, $fallback: null) {
+  @if not is-font-size-scale-valid($scale) {
+    @error 'Invalid font-size scale #{$scale}. Please choose one of #{$primitive-font-size-scales}';
+  }
+
+  $varname: --#{$primitive-prefix}-font-size-#{$scale};
+
+  @if not $fallback {
+    @return var(#{$varname});
+  }
+
+  @return var(#{$varname}, $fallback);
+}
+
+// Get line-height CSS variable
+@function line-height-variable($type, $fallback: null) {
+  @if not is-line-height-type-valid($type) {
+    @error 'Invalid line-height type #{$type}. Please choose one of #{$primitive-line-height-types}';
+  }
+
+  $varname: --#{$primitive-prefix}-line-height-#{$type};
+
+  @if not $fallback {
+    @return var(#{$varname});
+  }
+
+  @return var(#{$varname}, $fallback);
+}
+
+// Get letter-spacing CSS variable
+@function letter-spacing-variable($type, $fallback: null) {
+  @if not is-letter-spacing-type-valid($type) {
+    @error 'Invalid letter-spacing type #{$type}. Please choose one of #{$primitive-letter-spacing-types}';
+  }
+
+  $varname: --#{$primitive-prefix}-letter-spacing-#{$type};
+
+  @if not $fallback {
+    @return var(#{$varname});
+  }
+
+  @return var(#{$varname}, $fallback);
+}
+
+// Get default font-family list from primitives
+@function get-font-family-list($font-families: ()) {
+  $merged-font-families: map.merge($default-font-families, $font-families);
+  $result: ();
+
+  // 按照指定順序：PingFang TC, Noto Sans TC, SF Mono, sans-serif
+  @if map.has-key($merged-font-families, pingfangtc) {
+    $result: list.append($result, map.get($merged-font-families, pingfangtc), comma);
+  }
+
+  @if map.has-key($merged-font-families, notosans) {
+    $result: list.append($result, map.get($merged-font-families, notosans), comma);
+  }
+
+  @if map.has-key($merged-font-families, sfmono) {
+    $result: list.append($result, map.get($merged-font-families, sfmono), comma);
+  }
+
+  // 添加 sans-serif 作為最終回退
+  $result: list.append($result, sans-serif, comma);
+
+  @return $result;
+}
+
+// ==========================================
+// Generate CSS Variables Mixin
+// ==========================================
+
+// Generate partial font-family CSS variables
+@mixin partial-font-family-variables($font-families: ()) {
+  @each $type, $value in $font-families {
+    @if not is-font-family-type-valid($type) {
+      @error 'Invalid font-family type #{$type}. Please choose one of #{$primitive-font-family-types}';
+    }
+
+    @if $value {
+      --#{$primitive-prefix}-font-family-#{$type}: #{meta.inspect($value)};
+    }
+  }
+}
+
+// Generate partial font-weight CSS variables
+@mixin partial-font-weight-variables($font-weights: ()) {
+  @each $type, $value in $font-weights {
+    @if not is-font-weight-type-valid($type) {
+      @error 'Invalid font-weight type #{$type}. Please choose one of #{$primitive-font-weight-types}';
+    }
+
+    @if $value {
+      --#{$primitive-prefix}-font-weight-#{$type}: #{$value};
+    }
+  }
+}
+
+// Generate partial font-size CSS variables
+@mixin partial-font-size-variables($font-sizes: ()) {
+  @each $scale, $value in $font-sizes {
+    @if not is-font-size-scale-valid($scale) {
+      @error 'Invalid font-size scale #{$scale}. Please choose one of #{$primitive-font-size-scales}';
+    }
+
+    @if $value {
+      --#{$primitive-prefix}-font-size-#{$scale}: #{$value};
+    }
+  }
+}
+
+// Generate partial line-height CSS variables
+@mixin partial-line-height-variables($line-heights: ()) {
+  @each $type, $value in $line-heights {
+    @if not is-line-height-type-valid($type) {
+      @error 'Invalid line-height type #{$type}. Please choose one of #{$primitive-line-height-types}';
+    }
+
+    @if $value {
+      --#{$primitive-prefix}-line-height-#{$type}: #{$value};
+    }
+  }
+}
+
+// Generate partial letter-spacing CSS variables
+@mixin partial-letter-spacing-variables($letter-spacings: ()) {
+  @each $type, $value in $letter-spacings {
+    @if not is-letter-spacing-type-valid($type) {
+      @error 'Invalid letter-spacing type #{$type}. Please choose one of #{$primitive-letter-spacing-types}';
+    }
+
+    @if $value {
+      --#{$primitive-prefix}-letter-spacing-#{$type}: #{$value};
+    }
+  }
+}
+
+// Generate all typography primitive CSS variables
+@mixin variables(
+  $font-families: (),
+  $font-weights: (),
+  $font-sizes: (),
+  $line-heights: (),
+  $letter-spacings: ()
+) {
+  // Merge user values with defaults
+  $merged-font-families: map.merge($default-font-families, $font-families);
+  $merged-font-weights: map.merge($default-font-weights, $font-weights);
+  $merged-font-sizes: map.merge($default-font-sizes, $font-sizes);
+  $merged-line-heights: map.merge($default-line-heights, $line-heights);
+  $merged-letter-spacings: map.merge($default-letter-spacings, $letter-spacings);
+
+  @include partial-font-family-variables($merged-font-families);
+  @include partial-font-weight-variables($merged-font-weights);
+  @include partial-font-size-variables($merged-font-sizes);
+  @include partial-line-height-variables($merged-line-heights);
+  @include partial-letter-spacing-variables($merged-letter-spacings);
+}

package/typography/_semantic.scss

@@ -0,0 +1,237 @@
+@use '../utils/list';
+@use '../utils/map';
+@use './primitives' as primitive;
+
+$prefix: mzn-typography;
+
+// 定義所有 semantic 類型
+$semantic-types: (
+  h1,
+  h2,
+  h3,
+  body,
+  body-highlight,
+  body-mono,
+  body-mono-highlight,
+  text-link-body,
+  text-link-caption,
+  caption,
+  caption-highlight,
+  annotation,
+  annotation-highlight,
+  button,
+  button-highlight,
+  input,
+  input-mono,
+  label-primary,
+  label-primary-highlight,
+  label-secondary
+);
+
+// 定義所有 typography 屬性
+$semantic-props: (
+  font-family,
+  font-size,
+  font-weight,
+  line-height,
+  letter-spacing
+);
+
+// Semantic Typography 定義
+$semantic-typographies: (
+  h1: (
+    font-size: primitive.font-size-variable(24),
+    font-weight: primitive.font-weight-variable(semibold),
+    line-height: primitive.line-height-variable(h1),
+    letter-spacing: primitive.letter-spacing-variable(0),
+  ),
+  h2: (
+    font-size: primitive.font-size-variable(18),
+    font-weight: primitive.font-weight-variable(semibold),
+    line-height: primitive.line-height-variable(h2),
+    letter-spacing: primitive.letter-spacing-variable(0),
+  ),
+  h3: (
+    font-size: primitive.font-size-variable(16),
+    font-weight: primitive.font-weight-variable(semibold),
+    line-height: primitive.line-height-variable(h3),
+    letter-spacing: primitive.letter-spacing-variable(0),
+  ),
+  body: (
+    font-size: primitive.font-size-variable(14),
+    font-weight: primitive.font-weight-variable(regular),
+    line-height: primitive.line-height-variable(body),
+    letter-spacing: primitive.letter-spacing-variable(0),
+  ),
+  body-highlight: (
+    font-size: primitive.font-size-variable(14),
+    font-weight: primitive.font-weight-variable(medium),
+    line-height: primitive.line-height-variable(body),
+    letter-spacing: primitive.letter-spacing-variable(0),
+  ),
+  body-mono: (
+    font-family: primitive.font-family-variable(sfmono),
+    font-size: primitive.font-size-variable(14),
+    font-weight: primitive.font-weight-variable(regular),
+    line-height: primitive.line-height-variable(body),
+    letter-spacing: primitive.letter-spacing-variable(0),
+  ),
+  body-mono-highlight: (
+    font-family: primitive.font-family-variable(sfmono),
+    font-size: primitive.font-size-variable(14),
+    font-weight: primitive.font-weight-variable(medium),
+    line-height: primitive.line-height-variable(body),
+    letter-spacing: primitive.letter-spacing-variable(0),
+  ),
+  text-link-body: (
+    font-size: primitive.font-size-variable(14),
+    font-weight: primitive.font-weight-variable(regular),
+    line-height: primitive.line-height-variable(body),
+    letter-spacing: primitive.letter-spacing-variable(0),
+  ),
+  text-link-caption: (
+    font-size: primitive.font-size-variable(12),
+    font-weight: primitive.font-weight-variable(regular),
+    line-height: primitive.line-height-variable(caption),
+    letter-spacing: primitive.letter-spacing-variable(0),
+  ),
+  caption: (
+    font-size: primitive.font-size-variable(12),
+    font-weight: primitive.font-weight-variable(regular),
+    line-height: primitive.line-height-variable(caption),
+    letter-spacing: primitive.letter-spacing-variable(0),
+  ),
+  caption-highlight: (
+    font-size: primitive.font-size-variable(12),
+    font-weight: primitive.font-weight-variable(semibold),
+    line-height: primitive.line-height-variable(caption),
+    letter-spacing: primitive.letter-spacing-variable(0),
+  ),
+  annotation: (
+    font-size: primitive.font-size-variable(10),
+    font-weight: primitive.font-weight-variable(regular),
+    line-height: primitive.line-height-variable(annotation),
+    letter-spacing: primitive.letter-spacing-variable(0),
+  ),
+  annotation-highlight: (
+    font-size: primitive.font-size-variable(10),
+    font-weight: primitive.font-weight-variable(semibold),
+    line-height: primitive.line-height-variable(annotation),
+    letter-spacing: primitive.letter-spacing-variable(0),
+  ),
+  button: (
+    font-size: primitive.font-size-variable(14),
+    font-weight: primitive.font-weight-variable(regular),
+    line-height: primitive.line-height-variable(functional),
+    letter-spacing: primitive.letter-spacing-variable(0),
+  ),
+  button-highlight: (
+    font-size: primitive.font-size-variable(14),
+    font-weight: primitive.font-weight-variable(medium),
+    line-height: primitive.line-height-variable(functional),
+    letter-spacing: primitive.letter-spacing-variable(0),
+  ),
+  input: (
+    font-size: primitive.font-size-variable(14),
+    font-weight: primitive.font-weight-variable(regular),
+    line-height: primitive.line-height-variable(functional),
+    letter-spacing: primitive.letter-spacing-variable(0),
+  ),
+  input-mono: (
+    font-family: primitive.font-family-variable(sfmono),
+    font-size: primitive.font-size-variable(14),
+    font-weight: primitive.font-weight-variable(regular),
+    line-height: primitive.line-height-variable(functional),
+    letter-spacing: primitive.letter-spacing-variable(0),
+  ),
+  label-primary: (
+    font-size: primitive.font-size-variable(14),
+    font-weight: primitive.font-weight-variable(regular),
+    line-height: primitive.line-height-variable(functional),
+    letter-spacing: primitive.letter-spacing-variable(0),
+  ),
+  label-primary-highlight: (
+    font-size: primitive.font-size-variable(14),
+    font-weight: primitive.font-weight-variable(medium),
+    line-height: primitive.line-height-variable(functional),
+    letter-spacing: primitive.letter-spacing-variable(0),
+  ),
+  label-secondary: (
+    font-size: primitive.font-size-variable(12),
+    font-weight: primitive.font-weight-variable(regular),
+    line-height: primitive.line-height-variable(functional),
+    letter-spacing: primitive.letter-spacing-variable(0),
+  ),
+);
+
+@function is-semantic-type-valid($type) {
+  @return list.includes($semantic-types, $type);
+}
+
+@function is-semantic-prop-valid($prop) {
+  @return list.includes($semantic-props, $prop);
+}
+
+// Get semantic typography CSS variable name
+@function get-semantic-var-name($type, $prop) {
+  @return --#{$prefix}-#{$type}-#{$prop};
+}
+
+// Get semantic typography property value as CSS variable
+@function prop($type, $prop) {
+  @if not is-semantic-type-valid($type) {
+    @error 'Invalid semantic type #{$type}. Please choose one of #{$semantic-types}';
+  }
+
+  @if not is-semantic-prop-valid($prop) {
+    @error 'Invalid property #{$prop}. Please choose one of #{$semantic-props}';
+  }
+
+  @return var(#{get-semantic-var-name($type, $prop)});
+}
+
+// Generate all semantic typography CSS variables
+@mixin variables($typographies: ()) {
+  // Merge user typographies with default typographies
+  $merged-typographies: map.deep-merge($semantic-typographies, $typographies);
+
+  @each $type, $props in $merged-typographies {
+    @if not is-semantic-type-valid($type) {
+      @error 'Invalid semantic type #{$type}. Please choose one of #{$semantic-types}';
+    }
+
+    @each $prop, $value in $props {
+      @if not is-semantic-prop-valid($prop) {
+        @error 'Invalid property #{$prop}. Please choose one of #{$semantic-props}';
+      }
+
+      @if $value {
+        #{get-semantic-var-name($type, $prop)}: #{$value};
+      }
+    }
+  }
+}
+
+// Apply Semantic Typography Mixin
+@mixin variable($type, $exclude-props: ()) {
+  @if not is-semantic-type-valid($type) {
+    @error 'Invalid semantic type #{$type}. Please choose one of #{$semantic-types}';
+  }
+
+  // Validate exclude props
+  @each $prop in $exclude-props {
+    @if not is-semantic-prop-valid($prop) {
+      @error 'Invalid property #{$prop}. Please choose one of #{$semantic-props}';
+    }
+  }
+
+  $typography: map.get($semantic-typographies, $type);
+
+  @each $prop in $semantic-props {
+    @if not list.includes($exclude-props, $prop) {
+      @if map.has-key($typography, $prop) {
+        #{$prop}: var(--#{$prefix}-#{$type}-#{$prop});
+      }
+    }
+  }
+}