fokus-styles 2.0.0 → 2.3.0

package/packages/fokus-core/scss/tokens/_root.scss

@@ -55,12 +55,26 @@
     --fs-control-padding-x-lg: 16px;
     --fs-focus-width: 2px;
     --fs-focus-offset: 2px;
+    --fs-focus-color: var(--fs-color-primary);
+    --fs-focus-ring-size: 3px;
+    --fs-focus-ring-color: color-mix(in srgb, var(--fs-focus-color) 22%, transparent);
     --fs-focus-ring-alpha: 22%;
     --fs-transition-fast: 150ms;
     --fs-transition-normal: 220ms;
+    --fs-motion-duration-fast: var(--fs-transition-fast);
+    --fs-motion-duration-normal: var(--fs-transition-normal);
+    --fs-motion-ease-standard: var(--fs-ease-standard);
     --fs-ease-standard: cubic-bezier(0.2, 0, 0, 1);
     --fs-border-width: 1px;
     --fs-disabled-opacity: 0.5;
+    --fs-safe-area-top: env(safe-area-inset-top, 0px);
+    --fs-safe-area-right: env(safe-area-inset-right, 0px);
+    --fs-safe-area-bottom: env(safe-area-inset-bottom, 0px);
+    --fs-safe-area-left: env(safe-area-inset-left, 0px);
+    --fs-component-control-height: var(--fs-control-height);
+    --fs-component-overlay-backdrop: rgb(0 0 0 / 55%);
+    --fs-component-panel-radius: var(--fs-radius-md);
+    --fs-component-panel-shadow: var(--fs-shadow-lg);
 
     // Referência dos limiares usados pelos utilitários `@container` (ver
     // `packages/fokus-utilities/scss/utilities/_container-queries.scss`).

package/packages/fokus-core/scss/tools/_mixins.scss

@@ -3,6 +3,14 @@
 @use "sass:color";
 @use "../settings" as *;
 
+@mixin fs-fluid-type($min, $max, $min-vw: 320px, $max-vw: 1280px) {
+  font-size: clamp($min, calc(#{$min} + (#{ $max } - #{ $min }) * ((100vw - #{ $min-vw }) / (#{ $max-vw } - #{ $min-vw }))), $max);
+}
+
+@mixin fs-fluid-value($property, $min, $max, $min-vw: 320px, $max-vw: 1280px) {
+  #{$property}: clamp($min, calc(#{$min} + (#{ $max } - #{ $min }) * ((100vw - #{ $min-vw }) / (#{ $max-vw } - #{ $min-vw }))), $max);
+}
+
 @mixin media-breakpoint-up($name) {
   $min: map.get($breakpoints, $name);
 

package/packages/fokus-js/js/accordion.js

@@ -7,7 +7,8 @@ let idCounter = 0;
 export class Accordion {
   constructor(accordionEl) {
     this.accordionEl = accordionEl;
-    this.exclusive = accordionEl.getAttribute("data-multiple") !== "true";
+    this.exclusive = accordionEl.getAttribute("data-multiple") !== "true" && accordionEl.getAttribute("data-fs-always-open") !== "true";
+    this.alwaysOpen = accordionEl.getAttribute("data-fs-always-open") === "true";
     this.items = [];
 
     const buttons = Array.from(accordionEl.querySelectorAll(".fs-accordion-button"));
@@ -46,6 +47,7 @@ export class Accordion {
     const isOpen = entry.button.getAttribute("aria-expanded") === "true";
 
     if (isOpen) {
+      if (this.alwaysOpen) return;
       this._close(entry);
       return;
     }
@@ -60,17 +62,21 @@ export class Accordion {
   }
 
   _open(entry) {
+    entry.button.dispatchEvent(new CustomEvent("fs:show", { bubbles: true }));
     entry.button.setAttribute("aria-expanded", "true");
     entry.panel.hidden = false;
     expand(entry.panel).then(() => {
+      entry.button.dispatchEvent(new CustomEvent("fs:shown", { bubbles: true }));
       entry.button.dispatchEvent(new CustomEvent("fs:accordion:shown", { bubbles: true }));
     });
   }
 
   _close(entry) {
+    entry.button.dispatchEvent(new CustomEvent("fs:hide", { bubbles: true }));
     entry.button.setAttribute("aria-expanded", "false");
     collapse(entry.panel).then(() => {
       entry.panel.hidden = true;
+      entry.button.dispatchEvent(new CustomEvent("fs:hidden", { bubbles: true }));
       entry.button.dispatchEvent(new CustomEvent("fs:accordion:hidden", { bubbles: true }));
     });
   }

package/packages/fokus-js/js/core/focus.js

@@ -6,6 +6,23 @@ export function getFocusableElements(container) {
 }
 
 export function createFocusTrap(container) {
+  const inertSiblings = [];
+  const setSiblingsInert = (value) => {
+    if (!container.parentElement) return;
+    [...container.parentElement.children].filter((el) => el !== container).forEach((el) => {
+      if (value) {
+        inertSiblings.push({ el, value: el.inert, ariaHidden: el.getAttribute("aria-hidden") });
+        el.inert = true;
+        el.setAttribute("aria-hidden", "true");
+      } else {
+        const previous = inertSiblings.find((item) => item.el === el);
+        if (previous) {
+          el.inert = previous.value;
+          previous.ariaHidden === null ? el.removeAttribute("aria-hidden") : el.setAttribute("aria-hidden", previous.ariaHidden);
+        }
+      }
+    });
+  };
   function handleKeydown(event) {
     if (event.key !== "Tab") return;
 
@@ -32,11 +49,14 @@ export function createFocusTrap(container) {
 
   return {
     activate() {
+      setSiblingsInert(true);
       const focusable = getFocusableElements(container);
       if (focusable.length > 0) focusable[0].focus();
     },
     deactivate() {
       container.removeEventListener("keydown", handleKeydown);
+      setSiblingsInert(false);
+      inertSiblings.length = 0;
     },
   };
 }

package/packages/fokus-js/js/core/overlay.d.ts

@@ -1,3 +1,5 @@
 export function lockScroll(): void;
 export function unlockScroll(): void;
 export function onClickOutside(el: Element, callback: (event: MouseEvent) => void): () => void;
+export function registerOverlay(instance: { hide?: () => void }): void;
+export function unregisterOverlay(instance: { hide?: () => void }): void;

package/packages/fokus-js/js/core/overlay.js

@@ -2,6 +2,16 @@ let lockCount = 0;
 let paddingCompensated = false;
 let previousOverflow = "";
 let previousPaddingRight = "";
+const activeOverlays = [];
+
+export function registerOverlay(instance) {
+  if (!activeOverlays.includes(instance)) activeOverlays.push(instance);
+}
+
+export function unregisterOverlay(instance) {
+  const index = activeOverlays.lastIndexOf(instance);
+  if (index >= 0) activeOverlays.splice(index, 1);
+}
 
 export function lockScroll() {
   lockCount += 1;

package/packages/fokus-js/js/core/register.js

@@ -14,11 +14,13 @@ export function createInstanceRegistry() {
   };
 }
 
-export function autoInit(name, Ctor) {
+export function autoInit(name, Ctor, options = {}) {
   if (typeof document === "undefined") return;
 
+  const selector = options.selector ?? `[data-fs="${name}"]`;
+
   const init = () => {
-    document.querySelectorAll(`[data-fs="${name}"]`).forEach((el) => {
+    document.querySelectorAll(selector).forEach((el) => {
       if (!Ctor.getInstance(el)) new Ctor(el);
     });
   };

package/packages/fokus-js/js/focus-trap.d.ts

@@ -0,0 +1,3 @@
+export declare function getFocusableElements(container: Element): Element[];
+export declare function createFocusTrap(container: Element): { activate(): void; deactivate(): void };
+export declare function onEscapeKey(callback: (event: KeyboardEvent) => void): () => void;

package/packages/fokus-js/js/focus-trap.js

@@ -0,0 +1 @@
+export { createFocusTrap, getFocusableElements, onEscapeKey } from "./core/focus.js";

package/packages/fokus-js/js/fokus.d.ts

@@ -24,3 +24,10 @@ export { CommandPalette } from "./command-palette.js";
 export { TreeView } from "./tree-view.js";
 export { RangeSlider } from "./range.js";
 export { FileUploadAdvanced } from "./file-upload-advanced.js";
+export { Theme } from "./theme.js";
+export { Navbar } from "./navbar.js";
+export { Scrollspy } from "./scrollspy.js";
+export { FormValidation } from "./form-validation.js";
+export { createFocusTrap, getFocusableElements, onEscapeKey } from "./focus-trap.js";
+export { Spinner } from "./spinner.js";
+export { Pagination } from "./pagination.js";

package/packages/fokus-js/js/fokus.js

@@ -24,3 +24,10 @@ export { CommandPalette } from "./command-palette.js";
 export { TreeView } from "./tree-view.js";
 export { RangeSlider } from "./range.js";
 export { FileUploadAdvanced } from "./file-upload-advanced.js";
+export { Theme } from "./theme.js";
+export { Navbar } from "./navbar.js";
+export { Scrollspy } from "./scrollspy.js";
+export { FormValidation } from "./form-validation.js";
+export { Spinner } from "./spinner.js";
+export { Pagination } from "./pagination.js";
+export { createFocusTrap, getFocusableElements, onEscapeKey } from "./focus-trap.js";

package/packages/fokus-js/js/form-validation.d.ts

@@ -0,0 +1,7 @@
+export declare class FormValidation {
+  constructor(form: HTMLFormElement);
+  static getInstance(form: HTMLFormElement): FormValidation | undefined;
+  static getOrCreateInstance(form: HTMLFormElement): FormValidation;
+  validate(event: SubmitEvent): boolean;
+  dispose(): void;
+}

package/packages/fokus-js/js/form-validation.js

@@ -0,0 +1,20 @@
+import { autoInit, createInstanceRegistry } from "./core/register.js";
+
+const instances = createInstanceRegistry();
+
+export class FormValidation {
+  constructor(form) { this.form = form; this._submit = (event) => this.validate(event); form.addEventListener("submit", this._submit); instances.set(form, this); }
+  static getInstance(el) { return instances.get(el); }
+  static getOrCreateInstance(el) { return this.getInstance(el) ?? new FormValidation(el); }
+  validate(event) {
+    const valid = this.form.checkValidity();
+    this.form.classList.add("fs-was-validated");
+    this.form.querySelectorAll('[required], [aria-required="true"]').forEach((field) => field.setAttribute("aria-invalid", String(!field.checkValidity())));
+    if (!valid) { event.preventDefault(); event.stopPropagation(); }
+    this.form.dispatchEvent(new CustomEvent("fs:form:validated", { bubbles: true, detail: { valid } }));
+    return valid;
+  }
+  dispose() { this.form.removeEventListener("submit", this._submit); instances.delete(this.form); }
+}
+
+autoInit("form-validation", FormValidation);

package/packages/fokus-js/js/modal.js

@@ -1,4 +1,4 @@
-import { lockScroll, unlockScroll, onClickOutside } from "./core/overlay.js";
+import { lockScroll, unlockScroll, onClickOutside, registerOverlay, unregisterOverlay } from "./core/overlay.js";
 import { createFocusTrap, onEscapeKey } from "./core/focus.js";
 import { autoInit, createInstanceRegistry } from "./core/register.js";
 
@@ -47,6 +47,14 @@ export class Modal {
     return instances.get(el);
   }
 
+  static getOrCreateInstance(el, options = {}) {
+    return this.getInstance(el) ?? new Modal(el, options);
+  }
+
+  static show(el, options = {}) { return this.getOrCreateInstance(el, options).show(); }
+  static hide(el) { return this.getInstance(el)?.hide(); }
+  static toggle(el, options = {}) { return this.getOrCreateInstance(el, options).toggle(); }
+
   _handleTriggerClick(event) {
     event.preventDefault();
     this.show();
@@ -60,7 +68,9 @@ export class Modal {
 
   show() {
     if (this.isOpen) return;
+    this.triggerEl.dispatchEvent(new CustomEvent("fs:show", { bubbles: true }));
     this.isOpen = true;
+    registerOverlay(this);
 
     this.modalEl.classList.add("is-open");
     this.modalEl.setAttribute("aria-hidden", "false");
@@ -73,12 +83,15 @@ export class Modal {
       this._outsideClickCleanup = onClickOutside(this.dialogEl, () => this.hide());
     }
 
+    this.triggerEl.dispatchEvent(new CustomEvent("fs:shown", { bubbles: true }));
     this.triggerEl.dispatchEvent(new CustomEvent("fs:modal:shown", { bubbles: true }));
   }
 
   hide() {
     if (!this.isOpen) return;
+    this.triggerEl.dispatchEvent(new CustomEvent("fs:hide", { bubbles: true }));
     this.isOpen = false;
+    unregisterOverlay(this);
 
     this.modalEl.classList.remove("is-open");
     this.modalEl.setAttribute("aria-hidden", "true");
@@ -92,6 +105,7 @@ export class Modal {
 
     this.triggerEl.focus();
 
+    this.triggerEl.dispatchEvent(new CustomEvent("fs:hidden", { bubbles: true }));
     this.triggerEl.dispatchEvent(new CustomEvent("fs:modal:hidden", { bubbles: true }));
   }
 
@@ -112,4 +126,4 @@ export class Modal {
   }
 }
 
-autoInit("modal", Modal);
+autoInit("modal", Modal, { selector: '[data-fs="modal"], [data-fs-toggle="modal"]' });

package/packages/fokus-js/js/navbar.d.ts

@@ -0,0 +1,10 @@
+export declare class Navbar {
+  constructor(element: Element);
+  static getInstance(element: Element): Navbar | undefined;
+  static getOrCreateInstance(element: Element): Navbar;
+  isOpen(): boolean;
+  show(): void;
+  hide(): void;
+  toggle(): void;
+  dispose(): void;
+}

package/packages/fokus-js/js/navbar.js

@@ -0,0 +1,27 @@
+import { autoInit, createInstanceRegistry } from "./core/register.js";
+
+const instances = createInstanceRegistry();
+
+export class Navbar {
+  constructor(navbarEl) {
+    this.navbarEl = navbarEl;
+    this.toggleEl = navbarEl.querySelector('[data-fs-toggle="navbar"]');
+    const target = this.toggleEl?.getAttribute("data-fs-target");
+    this.menuEl = target ? document.querySelector(target) : navbarEl.querySelector(".fs-navbar-collapse");
+    if (!this.toggleEl || !this.menuEl) return;
+    this._toggle = () => this.toggle();
+    this._escape = (event) => { if (event.key === "Escape" && this.isOpen()) this.hide(); };
+    this.toggleEl.addEventListener("click", this._toggle);
+    this.menuEl.addEventListener("keydown", this._escape);
+    instances.set(navbarEl, this);
+  }
+  static getInstance(el) { return instances.get(el); }
+  static getOrCreateInstance(el) { return this.getInstance(el) ?? new Navbar(el); }
+  isOpen() { return this.menuEl?.classList.contains("is-open"); }
+  show() { this.menuEl.classList.add("is-open"); this.menuEl.hidden = false; this.toggleEl.setAttribute("aria-expanded", "true"); this.navbarEl.dispatchEvent(new CustomEvent("fs:shown", { bubbles: true })); }
+  hide() { this.menuEl.classList.remove("is-open"); this.menuEl.hidden = true; this.toggleEl.setAttribute("aria-expanded", "false"); this.toggleEl.focus(); this.navbarEl.dispatchEvent(new CustomEvent("fs:hidden", { bubbles: true })); }
+  toggle() { this.isOpen() ? this.hide() : this.show(); }
+  dispose() { this.toggleEl?.removeEventListener("click", this._toggle); this.menuEl?.removeEventListener("keydown", this._escape); instances.delete(this.navbarEl); }
+}
+
+autoInit("navbar", Navbar);

package/packages/fokus-js/js/offcanvas.d.ts

@@ -12,6 +12,10 @@ export class Offcanvas {
   constructor(triggerEl: HTMLElement, options?: OffcanvasOptions);
 
   static getInstance(el: Element): Offcanvas | undefined;
+  static getOrCreateInstance(el: HTMLElement, options?: OffcanvasOptions): Offcanvas;
+  static show(el: HTMLElement, options?: OffcanvasOptions): void;
+  static hide(el: HTMLElement): void;
+  static toggle(el: HTMLElement, options?: OffcanvasOptions): void;
 
   show(): void;
   hide(): void;

package/packages/fokus-js/js/offcanvas.js

@@ -1,4 +1,4 @@
-import { lockScroll, unlockScroll, onClickOutside } from "./core/overlay.js";
+import { lockScroll, unlockScroll, onClickOutside, registerOverlay, unregisterOverlay } from "./core/overlay.js";
 import { createFocusTrap, onEscapeKey } from "./core/focus.js";
 import { autoInit, createInstanceRegistry } from "./core/register.js";
 
@@ -48,6 +48,14 @@ export class Offcanvas {
     return instances.get(el);
   }
 
+  static getOrCreateInstance(el, options = {}) {
+    return this.getInstance(el) ?? new Offcanvas(el, options);
+  }
+
+  static show(el, options = {}) { return this.getOrCreateInstance(el, options).show(); }
+  static hide(el) { return this.getInstance(el)?.hide(); }
+  static toggle(el, options = {}) { return this.getOrCreateInstance(el, options).toggle(); }
+
   _handleTriggerClick(event) {
     event.preventDefault();
     this.show();
@@ -61,7 +69,9 @@ export class Offcanvas {
 
   show() {
     if (this.isOpen) return;
+    this.triggerEl.dispatchEvent(new CustomEvent("fs:show", { bubbles: true }));
     this.isOpen = true;
+    registerOverlay(this);
 
     if (this.hasBackdrop) {
       this._backdropEl = document.createElement("div");
@@ -96,12 +106,15 @@ export class Offcanvas {
       });
     }
 
+    this.triggerEl.dispatchEvent(new CustomEvent("fs:shown", { bubbles: true }));
     this.triggerEl.dispatchEvent(new CustomEvent("fs:offcanvas:shown", { bubbles: true }));
   }
 
   hide() {
     if (!this.isOpen) return;
+    this.triggerEl.dispatchEvent(new CustomEvent("fs:hide", { bubbles: true }));
     this.isOpen = false;
+    unregisterOverlay(this);
 
     this.offcanvasEl.classList.remove("is-open");
     this.offcanvasEl.setAttribute("aria-hidden", "true");
@@ -118,6 +131,7 @@ export class Offcanvas {
 
     this.triggerEl.focus();
 
+    this.triggerEl.dispatchEvent(new CustomEvent("fs:hidden", { bubbles: true }));
     this.triggerEl.dispatchEvent(new CustomEvent("fs:offcanvas:hidden", { bubbles: true }));
   }
 
@@ -138,4 +152,4 @@ export class Offcanvas {
   }
 }
 
-autoInit("offcanvas", Offcanvas);
+autoInit("offcanvas", Offcanvas, { selector: '[data-fs="offcanvas"], [data-fs-toggle="offcanvas"]' });

package/packages/fokus-js/js/pagination.d.ts

@@ -0,0 +1,7 @@
+export declare class Pagination {
+  constructor(element: HTMLElement);
+  static getInstance(element: HTMLElement): Pagination | undefined;
+  static getOrCreateInstance(element: HTMLElement): Pagination;
+  goTo(page: number): void;
+  dispose(): void;
+}

package/packages/fokus-js/js/pagination.js

@@ -0,0 +1,38 @@
+import { autoInit, createInstanceRegistry } from "./core/register.js";
+
+const instances = createInstanceRegistry();
+export class Pagination {
+  constructor(element) {
+    this.element = element;
+    this.current = Number(element.getAttribute("data-fs-page")) || 1;
+    this.total = Number(element.getAttribute("data-fs-pages")) || element.querySelectorAll("[data-fs-page]").length || 1;
+    this._click = (event) => {
+      const button = event.target.closest("[data-fs-page]");
+      if (!button || !this.element.contains(button)) return;
+      event.preventDefault();
+      this.goTo(Number(button.getAttribute("data-fs-page")));
+    };
+    element.addEventListener("click", this._click);
+    instances.set(element, this);
+    this._render();
+  }
+  static getInstance(el) { return instances.get(el); }
+  static getOrCreateInstance(el) { return this.getInstance(el) ?? new Pagination(el); }
+  goTo(page) {
+    const next = Math.max(1, Math.min(this.total, page));
+    if (next === this.current) return;
+    this.current = next;
+    this.element.setAttribute("data-fs-page", String(next));
+    this._render();
+    this.element.dispatchEvent(new CustomEvent("fs:pagination:change", { bubbles: true, detail: { page: next, total: this.total } }));
+  }
+  _render() {
+    this.element.querySelectorAll("[data-fs-page]").forEach((item) => {
+      const active = Number(item.getAttribute("data-fs-page")) === this.current;
+      item.classList.toggle("is-active", active);
+      item.setAttribute("aria-current", active ? "page" : "false");
+    });
+  }
+  dispose() { this.element.removeEventListener("click", this._click); instances.delete(this.element); }
+}
+autoInit("pagination", Pagination);

package/packages/fokus-js/js/scrollspy.d.ts

@@ -0,0 +1,7 @@
+export declare class Scrollspy {
+  constructor(element: Element);
+  static getInstance(element: Element): Scrollspy | undefined;
+  static getOrCreateInstance(element: Element): Scrollspy;
+  activate(section: Element): void;
+  dispose(): void;
+}

package/packages/fokus-js/js/scrollspy.js

@@ -0,0 +1,26 @@
+import { autoInit, createInstanceRegistry } from "./core/register.js";
+
+const instances = createInstanceRegistry();
+
+export class Scrollspy {
+  constructor(navEl) {
+    this.navEl = navEl;
+    this.links = [...navEl.querySelectorAll('a[href^="#"]')];
+    this.sections = this.links.map((link) => document.querySelector(link.getAttribute("href"))).filter(Boolean);
+    this.observer = typeof IntersectionObserver === "undefined" ? null : new IntersectionObserver((entries) => entries.forEach((entry) => entry.isIntersecting && this.activate(entry.target)), { rootMargin: "-20% 0px -65%" });
+    this.sections.forEach((section) => this.observer?.observe(section));
+    this._onScroll = () => {
+      if (this.observer) return;
+      const current = this.sections.filter((section) => section.getBoundingClientRect().top <= window.innerHeight * 0.35).at(-1);
+      if (current) this.activate(current);
+    };
+    if (!this.observer) window.addEventListener("scroll", this._onScroll, { passive: true });
+    instances.set(navEl, this);
+  }
+  static getInstance(el) { return instances.get(el); }
+  static getOrCreateInstance(el) { return this.getInstance(el) ?? new Scrollspy(el); }
+  activate(section) { this.links.forEach((link) => link.classList.toggle("is-active", link.getAttribute("href") === `#${section.id}`)); this.navEl.dispatchEvent(new CustomEvent("fs:scrollspy:activate", { bubbles: true, detail: { section } })); }
+  dispose() { this.observer?.disconnect(); window.removeEventListener("scroll", this._onScroll); instances.delete(this.navEl); }
+}
+
+autoInit("scrollspy", Scrollspy);

package/packages/fokus-js/js/spinner.d.ts

@@ -0,0 +1,9 @@
+export declare class Spinner {
+  constructor(element: HTMLElement);
+  static getInstance(element: HTMLElement): Spinner | undefined;
+  static getOrCreateInstance(element: HTMLElement): Spinner;
+  start(): void;
+  stop(): void;
+  toggle(): void;
+  dispose(): void;
+}

package/packages/fokus-js/js/spinner.js

@@ -0,0 +1,18 @@
+import { autoInit, createInstanceRegistry } from "./core/register.js";
+
+const instances = createInstanceRegistry();
+export class Spinner {
+  constructor(element) {
+    this.element = element;
+    this._setLoading(element.hasAttribute("data-fs-loading") && element.getAttribute("data-fs-loading") !== "false");
+    instances.set(element, this);
+  }
+  static getInstance(el) { return instances.get(el); }
+  static getOrCreateInstance(el) { return this.getInstance(el) ?? new Spinner(el); }
+  _setLoading(value) { this.loading = value; this.element.toggleAttribute("aria-busy", value); this.element.toggleAttribute("data-fs-loading", value); }
+  start() { this._setLoading(true); this.element.dispatchEvent(new CustomEvent("fs:loading:start", { bubbles: true })); }
+  stop() { this._setLoading(false); this.element.dispatchEvent(new CustomEvent("fs:loading:stop", { bubbles: true })); }
+  toggle() { this.loading ? this.stop() : this.start(); }
+  dispose() { instances.delete(this.element); }
+}
+autoInit("spinner", Spinner);

package/packages/fokus-js/js/theme.d.ts

@@ -0,0 +1,9 @@
+export declare class Theme {
+  constructor(root?: Element);
+  static getInstance(root?: Element): Theme | undefined;
+  static getOrCreateInstance(root?: Element): Theme;
+  static set(mode: "light" | "dark" | "auto", root?: Element): Theme;
+  get(): string;
+  set(mode: "light" | "dark" | "auto"): Theme;
+  dispose(): void;
+}

package/packages/fokus-js/js/theme.js

@@ -0,0 +1,19 @@
+import { createInstanceRegistry } from "./core/register.js";
+
+const instances = createInstanceRegistry();
+
+export class Theme {
+  constructor(root = document.documentElement) { this.root = root; instances.set(root, this); }
+  static getInstance(root = document.documentElement) { return instances.get(root); }
+  static getOrCreateInstance(root = document.documentElement) { return this.getInstance(root) ?? new Theme(root); }
+  static set(mode, root = document.documentElement) { return this.getOrCreateInstance(root).set(mode); }
+  get() { return this.root.getAttribute("data-fs-theme") ?? this.root.getAttribute("data-theme") ?? "light"; }
+  set(mode) {
+    if (!["light", "dark", "auto"].includes(mode)) throw new TypeError("FokusStyles.Theme: modo inválido.");
+    this.root.setAttribute("data-fs-theme", mode);
+    this.root.setAttribute("data-theme", mode === "dark" ? "dark" : "light");
+    this.root.dispatchEvent(new CustomEvent("fs:theme:change", { bubbles: true, detail: { mode } }));
+    return this;
+  }
+  dispose() { instances.delete(this.root); }
+}

package/packages/fokus-js/js/toast.js

@@ -33,9 +33,11 @@ export class Toast {
 
   show() {
     if (this.isOpen) return;
+    this.toastEl.dispatchEvent(new CustomEvent("fs:show", { bubbles: true }));
     this.isOpen = true;
 
     expand(this.toastEl).then(() => {
+      this.toastEl.dispatchEvent(new CustomEvent("fs:shown", { bubbles: true }));
       this.toastEl.dispatchEvent(new CustomEvent("fs:toast:shown", { bubbles: true }));
     });
 
@@ -46,12 +48,14 @@ export class Toast {
 
   hide() {
     if (!this.isOpen) return;
+    this.toastEl.dispatchEvent(new CustomEvent("fs:hide", { bubbles: true }));
     this.isOpen = false;
 
     clearTimeout(this._hideTimer);
     this._hideTimer = null;
 
     collapse(this.toastEl).then(() => {
+      this.toastEl.dispatchEvent(new CustomEvent("fs:hidden", { bubbles: true }));
       this.toastEl.dispatchEvent(new CustomEvent("fs:toast:hidden", { bubbles: true }));
     });
   }

package/packages/fokus-utilities/scss/utilities/_api.scss

@@ -0,0 +1,48 @@
+@use "sass:map";
+@use "../../fokus-core/scss/settings" as *;
+@use "../../fokus-core/scss/tools" as tools;
+
+// Utility API do Fokus Styles: os mapas são públicos e podem ser estendidos
+// antes do @use do entry-point pelo consumidor.
+$fs-utility-colors: $theme-colors !default;
+$fs-utility-spacers: $spacers !default;
+$fs-utility-sizes: (25: 25%, 50: 50%, 75: 75%, 100: 100%, auto: auto) !default;
+
+@layer utilities {
+  @if fs-config-list-enabled(colors, color) {
+    @each $name, $value in $fs-utility-colors {
+      .fs-u-color-#{$name} { color: var(--fs-color-#{$name}, #{$value}) !important; }
+      .fs-u-bg-#{$name} { background-color: var(--fs-color-#{$name}, #{$value}) !important; }
+    }
+  }
+
+  @if fs-config-list-enabled(spacing, margin) and fs-config-list-enabled(spacing, padding) {
+    @each $name, $value in $fs-utility-spacers {
+      .fs-u-m-#{$name} { margin: $value !important; }
+      .fs-u-mx-#{$name} { margin-inline: $value !important; }
+      .fs-u-my-#{$name} { margin-block: $value !important; }
+      .fs-u-p-#{$name} { padding: $value !important; }
+      .fs-u-px-#{$name} { padding-inline: $value !important; }
+      .fs-u-py-#{$name} { padding-block: $value !important; }
+    }
+  }
+
+  @if fs-config-list-enabled(sizing, width) {
+    @each $name, $value in $fs-utility-sizes {
+      .fs-u-w-#{$name} { width: $value !important; }
+      .fs-u-h-#{$name} { height: $value !important; }
+    }
+  }
+
+  @if fs-config-get(responsive, true) {
+    @each $breakpoint, $min in $breakpoints {
+      @if $min != 0 {
+        @media (min-width: $min) {
+          .fs-u-d-#{$breakpoint}-flex { display: flex !important; }
+          .fs-u-d-#{$breakpoint}-none { display: none !important; }
+          .fs-u-text-#{$breakpoint}-start { text-align: start !important; }
+        }
+      }
+    }
+  }
+}

package/packages/fokus-utilities/scss/utilities/_index.scss

@@ -8,3 +8,5 @@
 @use "spacing";
 @use "typography";
 @use "visibility";
+@use "states";
+@use "api";

package/packages/fokus-utilities/scss/utilities/_states.scss

@@ -0,0 +1,19 @@
+@layer utilities {
+  .fs-u-focus-ring:focus-visible {
+    outline: var(--fs-focus-width) solid var(--fs-focus-color);
+    outline-offset: var(--fs-focus-offset);
+    box-shadow: 0 0 0 var(--fs-focus-ring-size) var(--fs-focus-ring-color);
+  }
+
+  .fs-u-disabled,
+  .fs-u-disabled[aria-disabled="true"] {
+    cursor: not-allowed;
+    opacity: var(--fs-disabled-opacity);
+    pointer-events: none;
+  }
+
+  @media print {
+    .fs-u-print-hidden { display: none !important; }
+    .fs-u-print-visible { display: block !important; }
+  }
+}