tyrell-components 1.0.0-TC46 → 1.0.0-TC47

package/lib/styles/wizard.d.ts

@@ -6,4 +6,4 @@
  * circles read the matching accent var directly (no `-bg` indirection), and
  * the brand-layer flavor seeds cascade through for per-shade control.
  */
-export declare const wizardStyles = "\n/* Theming tokens \u2014 every default chains back to the brand layer / global\n   scale tokens. */\n\n:host {\n  display: block;\n  width: var(--ty-wizard-width, 100%);   /* set by width attribute \u2014 not a public token */\n  height: var(--ty-wizard-height, 700px); /* set by height attribute \u2014 not a public token */\n  box-sizing: border-box;\n\n  /* State accents \u2014 the primary override surface. One variable retints the\n   * matching circle background, border, and glow. */\n  --ty-wizard-active-accent:    var(--ty-color-primary);\n  --ty-wizard-completed-accent: var(--ty-color-success);\n  --ty-wizard-error-accent:     var(--ty-color-danger);\n  --ty-wizard-pending-accent:   var(--ty-color-neutral);\n\n  /* Container chrome \u2014 routes through global scales. Override --ty-radius-lg\n   * or --ty-shadow-md app-wide and the wizard follows; override these locally\n   * to give the wizard a distinct look. */\n  --ty-wizard-bg:     var(--ty-surface-floating);\n  --ty-wizard-border: var(--ty-border);\n  --ty-wizard-radius: var(--ty-radius-lg, 12px);\n  --ty-wizard-shadow: var(--ty-shadow-md, 0 1px 3px 0 rgba(0, 0, 0, 0.1), 0 1px 2px -1px rgba(0, 0, 0, 0.1));\n\n  --ty-wizard-header-bg:      var(--ty-surface-content);\n  --ty-wizard-header-border:  var(--ty-border-soft, var(--ty-border));\n  --ty-wizard-header-padding: 24px 24px 16px;\n\n  --ty-wizard-progress-track:  var(--ty-border);\n  --ty-wizard-progress-fill:   var(--ty-wizard-completed-accent);\n  --ty-wizard-progress-height: 2px;\n\n  /* Motion \u2014 routes through global motion tokens if defined. */\n  --ty-wizard-transition-duration: var(--ty-transition-duration, 300ms);\n  --ty-wizard-transition-easing:   var(--ty-transition-easing, ease-in-out);\n\n  --ty-wizard-circle-size:         32px;\n  --ty-wizard-circle-border-width: 2px;\n\n  --ty-wizard-panels-bg: var(--ty-surface-elevated);\n\n  --ty-wizard-focus-outline: var(--ty-wizard-active-accent);\n}\n\n.wizard-container {\n  width: 100%;\n  height: 100%;\n  display: flex;\n  flex-direction: column;\n  position: relative;\n  box-sizing: border-box;\n  border-radius: var(--ty-wizard-radius);\n  border: 1px solid var(--ty-wizard-border);\n  background: var(--ty-wizard-bg);\n  box-shadow: var(--ty-wizard-shadow);\n  overflow: hidden;\n}\n\n.step-indicators-wrapper {\n  display: flex;\n  flex-direction: column;\n  flex-shrink: 0;\n  position: relative;\n  padding: var(--ty-wizard-header-padding);\n  border-bottom: 1px solid var(--ty-wizard-header-border);\n  background: var(--ty-wizard-header-bg);\n}\n\n/* Progress line, behind the step circles */\n.progress-line {\n  position: absolute;\n  /*\n   * With equal-width indicators (flex: 1), each takes 100%/N of the width.\n   * Circle centers sit at 50%/N from the left edge of each indicator.\n   * Inset = 50% / step-count from each side keeps the line between circle centres.\n   */\n  left: calc(50% / var(--ty-wizard-step-count, 4));\n  right: calc(50% / var(--ty-wizard-step-count, 4));\n  top: calc(var(--ty-wizard-circle-size, 32px) / 2 - 1px);\n  height: var(--ty-wizard-progress-height);\n  background: var(--ty-wizard-progress-track);\n  z-index: 0;\n  pointer-events: none;\n  transition: opacity var(--ty-wizard-transition-duration) var(--ty-wizard-transition-easing);\n}\n\n.progress-overlay {\n  position: absolute;\n  left: 0;\n  top: 0;\n  height: 100%;\n  background: var(--ty-wizard-progress-fill);\n  transition: width var(--ty-wizard-transition-duration) var(--ty-wizard-transition-easing);\n  will-change: width;\n}\n\n.step-indicators {\n  display: flex;\n  align-items: flex-start;\n  position: relative;\n}\n\n.step-indicator {\n  display: flex;\n  flex-direction: column;\n  align-items: center;\n  gap: 8px;\n  cursor: pointer;\n  background: transparent;\n  border: none;\n  padding: 0;\n  font: inherit;\n  transition: opacity 200ms;\n  flex: 1;\n  min-width: 0;\n}\n\n.step-indicator[aria-disabled=\"true\"] {\n  opacity: 0.4;\n  cursor: not-allowed;\n  pointer-events: none;\n}\n\n.step-indicator:focus-visible {\n  outline: 2px solid var(--ty-wizard-focus-outline);\n  outline-offset: 4px;\n  border-radius: 50%;\n}\n\n.step-circle {\n  width: var(--ty-wizard-circle-size);\n  height: var(--ty-wizard-circle-size);\n  border-radius: 50%;\n  border: var(--ty-wizard-circle-border-width) solid;\n  display: flex;\n  align-items: center;\n  justify-content: center;\n  position: relative;\n  z-index: 10;\n  transition: var(--ty-local-transition, all var(--ty-wizard-transition-duration) var(--ty-wizard-transition-easing));\n  box-sizing: border-box;\n  flex-shrink: 0;\n}\n\n.step-circle[data-state=\"completed\"] {\n  background: var(--ty-wizard-completed-accent);\n  border-color: var(--ty-color-success-strong);\n  /* Derived from the accent this circle actually paints, not from\n     --ty-solid-success-fg: the two diverge in dark mode (--ty-solid-l\n     dims solid fills by 0.25 L), which stranded white text at 3.5:1. */\n  color: oklch(\n    from var(--ty-wizard-completed-accent)\n      clamp(0, (var(--ty-solid-fg-threshold, 0.6) - l) * 1000, 1) 0 0\n  );\n  box-shadow: 0 0 0 4px color-mix(in oklab, var(--ty-wizard-completed-accent) 12%, transparent);\n}\n\n.step-circle[data-state=\"active\"] {\n  background: var(--ty-wizard-active-accent);\n  border-color: var(--ty-color-primary-strong);\n  color: oklch(\n    from var(--ty-wizard-active-accent)\n      clamp(0, (var(--ty-solid-fg-threshold, 0.6) - l) * 1000, 1) 0 0\n  );\n  box-shadow: 0 0 0 4px color-mix(in oklab, var(--ty-wizard-active-accent) 12%, transparent);\n}\n\n.step-circle[data-state=\"pending\"] {\n  background: var(--ty-surface-elevated);\n  border-color: var(--ty-border);\n  color: var(--ty-color-neutral);\n}\n\n.step-circle[data-state=\"error\"] {\n  background: var(--ty-wizard-error-accent);\n  border-color: var(--ty-color-danger-strong);\n  color: oklch(\n    from var(--ty-wizard-error-accent)\n      clamp(0, (var(--ty-solid-fg-threshold, 0.6) - l) * 1000, 1) 0 0\n  );\n  box-shadow: 0 0 0 4px color-mix(in oklab, var(--ty-wizard-error-accent) 12%, transparent);\n}\n\n.step-text {\n  display: flex;\n  flex-direction: column;\n  gap: 2px;\n  align-items: center;\n}\n\n.step-label {\n  font-size: var(--ty-font-sm, 14px);\n  font-weight: var(--ty-font-semibold, 600);\n  color: var(--ty-color-neutral);\n  transition: var(--ty-local-transition, color 200ms);\n}\n\n.step-indicator[aria-selected=\"true\"] .step-label {\n  color: var(--ty-color-neutral-strong);\n}\n\n.step-indicator[aria-selected=\"false\"] .step-label {\n  color: var(--ty-color-neutral);\n}\n\n.step-description {\n  font-size: var(--ty-font-xs, 12px);\n  font-weight: var(--ty-font-normal, 400);\n  color: var(--ty-color-neutral);\n  transition: var(--ty-local-transition, color 200ms);\n  text-align: center;\n  max-width: 120px;\n}\n\n.step-indicator[aria-selected=\"true\"] .step-description {\n  color: var(--ty-color-neutral-bold);\n}\n\n/* Custom indicator content via slots */\n::slotted([slot^=\"indicator-\"]) {\n  display: flex;\n  align-items: center;\n  justify-content: center;\n  width: 100%;\n  height: 100%;\n}\n\n.panels-viewport {\n  position: relative;\n  flex: 1;\n  overflow: hidden;\n  min-height: 0;\n  background: var(--ty-wizard-panels-bg);\n}\n\n/* Panels wrapper slides horizontally */\n.panels-wrapper {\n  display: flex;\n  height: 100%;\n  transition: transform var(--ty-wizard-transition-duration) var(--ty-wizard-transition-easing);\n  will-change: transform;\n}\n\n::slotted(ty-step) {\n  width: var(--ty-wizard-width, 100%);\n  height: 100%;\n  flex-shrink: 0;\n}\n\n@media (prefers-reduced-motion: reduce) {\n  .panels-wrapper {\n    transition-duration: 0ms !important;\n  }\n\n  .progress-overlay {\n    transition-duration: 0ms !important;\n  }\n\n  .step-circle {\n    transition-duration: 0ms !important;\n  }\n\n  .progress-line {\n    transition-duration: 0ms !important;\n  }\n}\n\n.sr-only {\n  position: absolute;\n  width: 1px;\n  height: 1px;\n  padding: 0;\n  margin: -1px;\n  overflow: hidden;\n  clip: rect(0, 0, 0, 0);\n  white-space: nowrap;\n  border-width: 0;\n}\n";
+export declare const wizardStyles = "\n/* Theming tokens \u2014 every default chains back to the brand layer / global\n   scale tokens. */\n\n:host {\n  display: block;\n  width: var(--ty-wizard-width, 100%);   /* set by width attribute \u2014 not a public token */\n  height: var(--ty-wizard-height, 700px); /* set by height attribute \u2014 not a public token */\n  box-sizing: border-box;\n\n  /* State accents \u2014 the primary override surface. One variable retints the\n   * matching circle background, border, and glow. */\n  --ty-wizard-active-accent:    var(--ty-color-primary);\n  --ty-wizard-completed-accent: var(--ty-color-success);\n  --ty-wizard-error-accent:     var(--ty-color-danger);\n  --ty-wizard-pending-accent:   var(--ty-color-neutral);\n\n  /* Container chrome \u2014 routes through global scales. Override --ty-radius-lg\n   * or --ty-shadow-md app-wide and the wizard follows; override these locally\n   * to give the wizard a distinct look. */\n  --ty-wizard-bg:     var(--ty-surface-floating);\n  --ty-wizard-border: var(--ty-border);\n  --ty-wizard-radius: var(--ty-radius-lg, 12px);\n  --ty-wizard-shadow: var(--ty-shadow-md, 0 1px 3px 0 rgba(0, 0, 0, 0.1), 0 1px 2px -1px rgba(0, 0, 0, 0.1));\n\n  --ty-wizard-header-bg:      var(--ty-surface-content);\n  --ty-wizard-header-border:  var(--ty-border-soft, var(--ty-border));\n  --ty-wizard-header-padding: 24px 24px 16px;\n\n  --ty-wizard-progress-track:  var(--ty-border);\n  --ty-wizard-progress-fill:   var(--ty-wizard-completed-accent);\n  --ty-wizard-progress-height: 2px;\n\n  /* Motion \u2014 routes through global motion tokens if defined. */\n  --ty-wizard-transition-duration: var(--ty-transition-duration, 300ms);\n  --ty-wizard-transition-easing:   var(--ty-transition-easing, ease-in-out);\n\n  --ty-wizard-circle-size:         32px;\n  --ty-wizard-circle-border-width: 2px;\n\n  --ty-wizard-panels-bg: var(--ty-surface-elevated);\n\n  --ty-wizard-focus-outline: var(--ty-wizard-active-accent);\n}\n\n.wizard-container {\n  width: 100%;\n  height: 100%;\n  display: flex;\n  flex-direction: column;\n  position: relative;\n  box-sizing: border-box;\n  border-radius: var(--ty-wizard-radius);\n  border: 1px solid var(--ty-wizard-border);\n  background: var(--ty-wizard-bg);\n  box-shadow: var(--ty-wizard-shadow);\n  overflow: hidden;\n}\n\n.step-indicators-wrapper {\n  display: flex;\n  flex-direction: column;\n  flex-shrink: 0;\n  position: relative;\n  padding: var(--ty-wizard-header-padding);\n  border-bottom: 1px solid var(--ty-wizard-header-border);\n  background: var(--ty-wizard-header-bg);\n}\n\n/* Progress line, behind the step circles */\n.progress-line {\n  position: absolute;\n  /*\n   * With equal-width indicators (flex: 1), each takes 100%/N of the width.\n   * Circle centers sit at 50%/N from the left edge of each indicator.\n   * Inset = 50% / step-count from each side keeps the line between circle centres.\n   */\n  left: calc(50% / var(--ty-wizard-step-count, 4));\n  right: calc(50% / var(--ty-wizard-step-count, 4));\n  top: calc(var(--ty-wizard-circle-size, 32px) / 2 - 1px);\n  height: var(--ty-wizard-progress-height);\n  background: var(--ty-wizard-progress-track);\n  z-index: 0;\n  pointer-events: none;\n  transition: opacity var(--ty-wizard-transition-duration) var(--ty-wizard-transition-easing);\n}\n\n.progress-overlay {\n  position: absolute;\n  left: 0;\n  top: 0;\n  height: 100%;\n  background: var(--ty-wizard-progress-fill);\n  transition: width var(--ty-wizard-transition-duration) var(--ty-wizard-transition-easing);\n  will-change: width;\n}\n\n.step-indicators {\n  display: flex;\n  align-items: flex-start;\n  position: relative;\n}\n\n.step-indicator {\n  display: flex;\n  flex-direction: column;\n  align-items: center;\n  gap: 8px;\n  cursor: pointer;\n  background: transparent;\n  border: none;\n  padding: 0;\n  font: inherit;\n  transition: opacity 200ms;\n  flex: 1;\n  min-width: 0;\n}\n\n.step-indicator[aria-disabled=\"true\"] {\n  opacity: 0.4;\n  cursor: not-allowed;\n  pointer-events: none;\n}\n\n.step-indicator:focus-visible {\n  outline: 2px solid var(--ty-wizard-focus-outline);\n  outline-offset: 4px;\n  border-radius: 50%;\n}\n\n.step-circle {\n  width: var(--ty-wizard-circle-size);\n  height: var(--ty-wizard-circle-size);\n  border-radius: 50%;\n  border: var(--ty-wizard-circle-border-width) solid;\n  display: flex;\n  align-items: center;\n  justify-content: center;\n  position: relative;\n  z-index: 10;\n  transition: var(--ty-local-transition, all var(--ty-wizard-transition-duration) var(--ty-wizard-transition-easing));\n  box-sizing: border-box;\n  flex-shrink: 0;\n}\n\n.step-circle[data-state=\"completed\"] {\n  background: var(--ty-wizard-completed-accent);\n  border-color: var(--ty-color-success-strong);\n  /* Derived from the accent this circle actually paints, not from\n     --ty-solid-success-fg: the two diverge in dark mode (--ty-solid-l\n     dims solid fills by 0.25 L), which stranded white text at 3.5:1. */\n  color: oklch(\n    from var(--ty-wizard-completed-accent)\n      clamp(0, (var(--ty-solid-fg-threshold, 0.57) - l) * 1000, 1) 0 0\n  );\n  box-shadow: 0 0 0 4px color-mix(in oklab, var(--ty-wizard-completed-accent) 12%, transparent);\n}\n\n.step-circle[data-state=\"active\"] {\n  background: var(--ty-wizard-active-accent);\n  border-color: var(--ty-color-primary-strong);\n  color: oklch(\n    from var(--ty-wizard-active-accent)\n      clamp(0, (var(--ty-solid-fg-threshold, 0.57) - l) * 1000, 1) 0 0\n  );\n  box-shadow: 0 0 0 4px color-mix(in oklab, var(--ty-wizard-active-accent) 12%, transparent);\n}\n\n.step-circle[data-state=\"pending\"] {\n  background: var(--ty-surface-elevated);\n  border-color: var(--ty-border);\n  color: var(--ty-color-neutral);\n}\n\n.step-circle[data-state=\"error\"] {\n  background: var(--ty-wizard-error-accent);\n  border-color: var(--ty-color-danger-strong);\n  color: oklch(\n    from var(--ty-wizard-error-accent)\n      clamp(0, (var(--ty-solid-fg-threshold, 0.57) - l) * 1000, 1) 0 0\n  );\n  box-shadow: 0 0 0 4px color-mix(in oklab, var(--ty-wizard-error-accent) 12%, transparent);\n}\n\n.step-text {\n  display: flex;\n  flex-direction: column;\n  gap: 2px;\n  align-items: center;\n}\n\n.step-label {\n  font-size: var(--ty-font-sm, 14px);\n  font-weight: var(--ty-font-semibold, 600);\n  color: var(--ty-color-neutral);\n  transition: var(--ty-local-transition, color 200ms);\n}\n\n.step-indicator[aria-selected=\"true\"] .step-label {\n  color: var(--ty-color-neutral-strong);\n}\n\n.step-indicator[aria-selected=\"false\"] .step-label {\n  color: var(--ty-color-neutral);\n}\n\n.step-description {\n  font-size: var(--ty-font-xs, 12px);\n  font-weight: var(--ty-font-normal, 400);\n  color: var(--ty-color-neutral);\n  transition: var(--ty-local-transition, color 200ms);\n  text-align: center;\n  max-width: 120px;\n}\n\n.step-indicator[aria-selected=\"true\"] .step-description {\n  color: var(--ty-color-neutral-bold);\n}\n\n/* Custom indicator content via slots */\n::slotted([slot^=\"indicator-\"]) {\n  display: flex;\n  align-items: center;\n  justify-content: center;\n  width: 100%;\n  height: 100%;\n}\n\n.panels-viewport {\n  position: relative;\n  flex: 1;\n  overflow: hidden;\n  min-height: 0;\n  background: var(--ty-wizard-panels-bg);\n}\n\n/* Panels wrapper slides horizontally */\n.panels-wrapper {\n  display: flex;\n  height: 100%;\n  transition: transform var(--ty-wizard-transition-duration) var(--ty-wizard-transition-easing);\n  will-change: transform;\n}\n\n::slotted(ty-step) {\n  width: var(--ty-wizard-width, 100%);\n  height: 100%;\n  flex-shrink: 0;\n}\n\n@media (prefers-reduced-motion: reduce) {\n  .panels-wrapper {\n    transition-duration: 0ms !important;\n  }\n\n  .progress-overlay {\n    transition-duration: 0ms !important;\n  }\n\n  .step-circle {\n    transition-duration: 0ms !important;\n  }\n\n  .progress-line {\n    transition-duration: 0ms !important;\n  }\n}\n\n.sr-only {\n  position: absolute;\n  width: 1px;\n  height: 1px;\n  padding: 0;\n  margin: -1px;\n  overflow: hidden;\n  clip: rect(0, 0, 0, 0);\n  white-space: nowrap;\n  border-width: 0;\n}\n";

package/lib/styles/wizard.js

@@ -151,7 +151,7 @@ export const wizardStyles = `
      dims solid fills by 0.25 L), which stranded white text at 3.5:1. */
   color: oklch(
     from var(--ty-wizard-completed-accent)
-      clamp(0, (var(--ty-solid-fg-threshold, 0.6) - l) * 1000, 1) 0 0
+      clamp(0, (var(--ty-solid-fg-threshold, 0.57) - l) * 1000, 1) 0 0
   );
   box-shadow: 0 0 0 4px color-mix(in oklab, var(--ty-wizard-completed-accent) 12%, transparent);
 }
@@ -161,7 +161,7 @@ export const wizardStyles = `
   border-color: var(--ty-color-primary-strong);
   color: oklch(
     from var(--ty-wizard-active-accent)
-      clamp(0, (var(--ty-solid-fg-threshold, 0.6) - l) * 1000, 1) 0 0
+      clamp(0, (var(--ty-solid-fg-threshold, 0.57) - l) * 1000, 1) 0 0
   );
   box-shadow: 0 0 0 4px color-mix(in oklab, var(--ty-wizard-active-accent) 12%, transparent);
 }
@@ -177,7 +177,7 @@ export const wizardStyles = `
   border-color: var(--ty-color-danger-strong);
   color: oklch(
     from var(--ty-wizard-error-accent)
-      clamp(0, (var(--ty-solid-fg-threshold, 0.6) - l) * 1000, 1) 0 0
+      clamp(0, (var(--ty-solid-fg-threshold, 0.57) - l) * 1000, 1) 0 0
   );
   box-shadow: 0 0 0 4px color-mix(in oklab, var(--ty-wizard-error-accent) 12%, transparent);
 }

package/lib/utils/positioning.d.ts

@@ -12,7 +12,7 @@ export type PlacementOrientation = 'horizontal' | 'vertical';
 /**
  * Vertical alignment options
  */
-export type VerticalAlign = 'top' | 'center' | 'bottom' | 'end';
+export type VerticalAlign = 'top' | 'start' | 'center' | 'bottom' | 'end';
 /**
  * Horizontal alignment options
  */
@@ -110,6 +110,47 @@ export declare const placementPreferences: {
     tooltip: Placement[];
     dropdown: Placement[];
 };
+/** The four sides a floating element can sit on. */
+export type PlacementSide = 'top' | 'right' | 'bottom' | 'left';
+/** Cross-axis alignment against the anchor. Omitted means centred. */
+export type PlacementAlign = 'start' | 'end';
+/** Split `'left-end'` into `{ side: 'left', align: 'end' }`. */
+export declare function parsePlacement(placement: Placement): {
+    side: PlacementSide;
+    align?: PlacementAlign;
+};
+/**
+ * Fallback order to try for a requested placement, best-fit first.
+ *
+ * FLIP BEFORE RE-ALIGN. When a placement overflows it is almost always the
+ * SIDE axis that ran out of room, and re-aligning on the same side does not
+ * change the fit at all: `bottom-start` and `bottom-end` need identical
+ * vertical space. Flipping to the opposite side is the move that actually
+ * helps, so the requested alignment is carried across the flip first, and only
+ * then do we try other alignments.
+ *
+ * This also keeps the old hand-written chains intact for the four bare sides —
+ * `top` still degrades to `bottom` as its very next candidate, exactly as
+ * before aligned placements existed.
+ *
+ * Callers previously hand-wrote a 4-entry chain per side, which silently
+ * dropped every aligned placement onto the default chain.
+ */
+export declare function preferenceChain(placement: Placement): Placement[];
+/**
+ * Map a `Placement` onto `computeAnchoredPosition`'s inputs, so dropdown-style
+ * components (ty-select, ty-date-picker) accept the same `placement` vocabulary
+ * as ty-popup / ty-tooltip.
+ *
+ * Dropdowns only ever live above or below their trigger, so a left/right
+ * placement degrades to "auto" side while keeping its alignment. Bare sides
+ * default to start-aligned, matching a native <select> and the behaviour these
+ * components had before `placement` existed.
+ */
+export declare function placementToAnchored(placement?: Placement | '' | null): {
+    side: 'top' | 'bottom' | 'auto';
+    align: 'start' | 'center' | 'end';
+};
 /**
  * Find the best position for the floating element
  * Tries all preference placements and returns the one that fits best
@@ -131,10 +172,14 @@ export interface AnchoredPopupOptions {
     gap?: number;
     /** Minimum distance from viewport edges (px, default 8) */
     padding?: number;
-    /** Horizontal anchor edge: trigger's left edge ("start", default) or
-     *  right edge ("end"). Either way the result is clamped into the
-     *  viewport, same as before. */
-    align?: "start" | "end";
+    /** Horizontal anchor edge: trigger's left edge ("start", default), its
+     *  right edge ("end"), or centred on it. Either way the result is clamped
+     *  into the viewport, same as before. */
+    align?: "start" | "center" | "end";
+    /** Preferred vertical side. "auto" (default) keeps the historic behaviour:
+     *  below when it fits, otherwise whichever side has more room. Naming a
+     *  side honours it when it fits and still flips rather than clipping. */
+    side?: "top" | "bottom" | "auto";
 }
 export interface AnchoredPopupPosition {
     /** Popup left edge, viewport coords, clamped into view */

package/lib/utils/positioning.js

@@ -12,7 +12,7 @@ export const placements = {
         horizontal: 'end',
     },
     'right-start': {
-        vertical: 'center',
+        vertical: 'start',
         horizontal: 'end',
         orientation: 'vertical',
     },
@@ -39,7 +39,7 @@ export const placements = {
         horizontal: 'end',
     },
     'left-start': {
-        vertical: 'center',
+        vertical: 'start',
         horizontal: 'start',
         orientation: 'vertical',
     },
@@ -68,6 +68,41 @@ export const placementPreferences = {
         'bottom', 'top', 'right', 'left'
     ],
 };
+const OPPOSITE_SIDE = {
+    top: 'bottom',
+    bottom: 'top',
+    left: 'right',
+    right: 'left',
+};
+export function parsePlacement(placement) {
+    const [side, align] = placement.split('-');
+    return { side, align };
+}
+export function preferenceChain(placement) {
+    const { side, align } = parsePlacement(placement);
+    const opposite = OPPOSITE_SIDE[side];
+    const perpendicular = side === 'top' || side === 'bottom' ? ['right', 'left'] : ['bottom', 'top'];
+    const exact = (s) => (align ? `${s}-${align}` : s);
+    const rest = (s) => (align
+        ? [s, `${s}-${align === 'start' ? 'end' : 'start'}`]
+        : [`${s}-start`, `${s}-end`]);
+    return [
+        exact(side),
+        exact(opposite),
+        ...rest(side),
+        ...rest(opposite),
+        ...perpendicular.flatMap((s) => [exact(s), ...rest(s)]),
+    ];
+}
+export function placementToAnchored(placement) {
+    if (!placement)
+        return { side: 'auto', align: 'start' };
+    const { side, align } = parsePlacement(placement);
+    return {
+        side: side === 'top' || side === 'bottom' ? side : 'auto',
+        align: align ?? 'start',
+    };
+}
 function getElementRect(el) {
     const rect = el.getBoundingClientRect();
     return {
@@ -123,7 +158,7 @@ function calculatePlacement(options) {
             y = targetRect.bottom - floatingRect.height - containerPadding;
         }
         else {
-            y = targetRect.top;
+            y = targetRect.top + containerPadding;
         }
     }
     else {
@@ -178,8 +213,17 @@ export function computeAnchoredPosition(o) {
     const vh = window.innerHeight;
     const spaceBelow = vh - o.anchorRect.bottom;
     const spaceAbove = o.anchorRect.top;
-    const below = spaceBelow >= o.popupHeight + gap + padding || spaceBelow >= spaceAbove;
-    const rawX = o.align === "end" ? o.anchorRect.right - o.popupWidth : o.anchorRect.left;
+    const needed = o.popupHeight + gap + padding;
+    const fitsBelow = spaceBelow >= needed;
+    const fitsAbove = spaceAbove >= needed;
+    const side = o.side ?? "auto";
+    const below = side === "bottom" ? (fitsBelow || !fitsAbove ? true : false)
+        : side === "top" ? (fitsAbove || !fitsBelow ? false : true)
+            : fitsBelow || spaceBelow >= spaceAbove;
+    const rawX = o.align === "end" ? o.anchorRect.right - o.popupWidth
+        : o.align === "center"
+            ? o.anchorRect.left + (o.anchorRect.width - o.popupWidth) / 2
+            : o.anchorRect.left;
     const x = Math.max(padding, Math.min(rawX, vw - o.popupWidth - padding));
     return {
         x,

package/lib/version.d.ts

@@ -4,4 +4,4 @@
  * This is automatically synced with package.json during build.
  * Use `npm version` to bump versions.
  */
-export declare const VERSION = "1.0.0-TC46";
+export declare const VERSION = "1.0.0-TC47";

package/lib/version.js

@@ -1 +1 @@
-export const VERSION = '1.0.0-TC46';
+export const VERSION = '1.0.0-TC47';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tyrell-components",
-  "version": "1.0.0-TC46",
+  "version": "1.0.0-TC47",
   "description": "Tyrell Components - Framework-agnostic web components with semantic design system",
   "type": "module",
   "sideEffects": [