@oksigenia/access-panel 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Oksigenia SL
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/NOTICE.md

@@ -0,0 +1,9 @@
+# NOTICE
+
+`@oksigenia/access-panel` is derived from the WordPress plugin
+[`oksigenia-access`](https://wordpress.org/plugins/oksigenia-access/)
+(GPLv2+) originally developed by Oksigenia SL.
+
+The TypeScript/web-component re-packaging in this directory is
+licensed under MIT (see `../../LICENSE`) per the dual-license intent
+of the original author. The WordPress distribution remains under GPLv2+.

package/README.md

@@ -0,0 +1,100 @@
+# @oksigenia/access-panel
+
+Accessibility panel as a web component. Drop in one tag, get 15 controls.
+
+- **15 controls**: text size (4 levels), line height (3), text alignment (3),
+  letter spacing (3), readable font toggle, dyslexia font toggle, high contrast,
+  grayscale overlay, hide images, highlight links, colorblind filters (3 types),
+  reading guide, big cursor, pause animations, focus outlines.
+- **8 locales**: es, en, gn (Guaraní), fr, it, de, nl, sv.
+- **Privacy-first**: zero dependencies, no analytics, no remote calls. User
+  preferences persist in `localStorage` only.
+- **Shadow DOM**: panel CSS is encapsulated; only the `body.oks-*` effect
+  classes (zoom, contrast, etc.) are inserted into `document.head`, with a
+  single, scoped `<style id="oksigenia-access-effects">`.
+- **A11y**: `role="dialog"`, `aria-modal`, focus trap, Escape closes,
+  `aria-pressed` on every control, `prefers-reduced-motion`-friendly.
+
+Originally developed by [Oksigenia](https://oksigenia.com) as the
+WordPress plugin
+[`oksigenia-access`](https://wordpress.org/plugins/oksigenia-access/),
+re-packaged as a framework-agnostic web library.
+
+## Install
+
+```sh
+npm i @oksigenia/access-panel
+```
+
+## Use it as a web component
+
+```html
+<script type="module">
+  import '@oksigenia/access-panel/web-component';
+</script>
+
+<oksigenia-access-panel
+  locale="es-PY"
+  position="mid-left"
+  trigger-icon="vitruvian"
+></oksigenia-access-panel>
+```
+
+Attributes:
+
+| Attribute | Default | Notes |
+|---|---|---|
+| `locale` | `navigator.language` | One of `es`, `en`, `gn`, `fr`, `it`, `de`, `nl`, `sv`. Regional variants (`es-PY` → `es`) work. |
+| `position` | `mid-left` | One of `top-left`, `top-right`, `mid-left`, `mid-right`, `bottom-left`, `bottom-right`. |
+| `trigger-icon` | `vitruvian` | One of `vitruvian`, `wheelchair`, `eye`, `universal`. |
+| `storage-key` | `oksiacSettings` | localStorage key for persisted preferences. |
+
+## Use it in Astro
+
+```astro
+---
+// src/layouts/Base.astro
+---
+<script>
+  import '@oksigenia/access-panel/web-component';
+</script>
+<oksigenia-access-panel locale="es-PY"></oksigenia-access-panel>
+```
+
+## Low-level building blocks
+
+If you want to render the panel manually or write your own behavior
+on top, the building blocks are exported:
+
+```ts
+import {
+  buildPanelHtml,
+  bindPanelBehavior,
+  loadState,
+  saveState,
+  PANEL_CSS,
+  EFFECT_CSS,
+  getTranslation,
+} from '@oksigenia/access-panel';
+```
+
+## Why a single component instead of 15
+
+Each control was hand-picked from real-world accessibility audits and
+user feedback collected across 2-3 years on the WordPress side. They
+intentionally cover three orthogonal axes:
+
+- **Text** (6 controls): size, line height, alignment, font swap, dyslexia
+  font, letter spacing.
+- **Vision** (5 controls): contrast, grayscale, hide images, highlight links,
+  colorblind filters.
+- **Orientation** (4 controls): reading guide, big cursor, pause animations,
+  focus outline.
+
+You can disable individual controls by hiding them with CSS in the
+shadow root if you want a smaller panel for your site, but the API
+contract is to ship the full set.
+
+## License
+
+[MIT](../../LICENSE) © [Oksigenia SL](https://oksigenia.com).

package/dist/index.d.ts

@@ -0,0 +1,90 @@
+type LocaleCode = 'es' | 'gn' | 'en' | 'fr' | 'it' | 'de' | 'nl' | 'sv';
+interface Translation {
+    title: string;
+    close: string;
+    txt: string;
+    size: string;
+    lh: string;
+    align: string;
+    font: string;
+    dyslexia: string;
+    vis: string;
+    contrast: string;
+    gray: string;
+    hide: string;
+    links: string;
+    ori: string;
+    guide: string;
+    cursor: string;
+    pause: string;
+    reset: string;
+    dev: string;
+    ls: string;
+    cb: string;
+    focus: string;
+}
+declare function getTranslation(locale: string): Translation;
+declare function supportedLocales(): readonly LocaleCode[];
+
+type TriggerIcon = 'vitruvian' | 'wheelchair' | 'eye' | 'universal';
+declare const COLORBLIND_FILTERS_SVG = "<svg xmlns=\"http://www.w3.org/2000/svg\" style=\"position:absolute;width:0;height:0;overflow:hidden;\" aria-hidden=\"true\"><defs><filter id=\"oks-filter-protanopia\"><feColorMatrix type=\"matrix\" values=\"0.567 0.433 0 0 0  0.558 0.442 0 0 0  0 0.242 0.758 0 0  0 0 0 1 0\"/></filter><filter id=\"oks-filter-deuteranopia\"><feColorMatrix type=\"matrix\" values=\"0.625 0.375 0 0 0  0.7 0.3 0 0 0  0 0.3 0.7 0 0  0 0 0 1 0\"/></filter><filter id=\"oks-filter-tritanopia\"><feColorMatrix type=\"matrix\" values=\"0.95 0.05 0 0 0  0 0.433 0.567 0 0  0 0.475 0.525 0 0  0 0 0 1 0\"/></filter></defs></svg>";
+
+type Position = 'top-left' | 'top-right' | 'mid-left' | 'mid-right' | 'bottom-left' | 'bottom-right';
+interface RenderOptions {
+    t: Translation;
+    triggerIcon: TriggerIcon;
+    position: Position;
+}
+/**
+ * HTML del panel completo (trigger + dialog). Pensado para inyectarse
+ * dentro del Shadow DOM del custom element.
+ */
+declare function buildPanelHtml(opts: RenderOptions): string;
+/** Mapea Position a CSS para wrapper y panel. Inyectado en el Shadow DOM. */
+declare function positionCss(position: Position): string;
+
+interface PanelState {
+    /** Niveles 1..4 → 0 desactivado. */
+    zoom: number;
+    /** Niveles 1..3 → 0 desactivado. */
+    lh: number;
+    /** Niveles 1..3 → 0 desactivado. */
+    align: number;
+    /** Niveles 1..3 → 0 desactivado. */
+    ls: number;
+    /** Niveles 1..3 (1=protanopia, 2=deuteranopia, 3=tritanopia). 0 desactivado. */
+    colorblind: number;
+    /** Toggles. */
+    font: boolean;
+    dyslexia: boolean;
+    contrast: boolean;
+    hideImages: boolean;
+    highlightLinks: boolean;
+    bigCursor: boolean;
+    pauseAnim: boolean;
+    focusOutline: boolean;
+    /** Overlay escala de grises (excluyente con contrast). */
+    grayOverlay: boolean;
+    /** Guía horizontal de lectura. */
+    readingGuide: boolean;
+}
+declare const DEFAULT_STATE: Readonly<PanelState>;
+declare function loadState(key: string): PanelState;
+declare function saveState(key: string, state: PanelState): void;
+declare function isStateEmpty(state: PanelState): boolean;
+
+interface BehaviorOptions {
+    /** Llave localStorage. Default oksiacSettings. */
+    storageKey?: string;
+}
+/**
+ * Engancha toda la lógica al panel ya renderizado dentro de `root`
+ * (que es el shadowRoot del custom element). Devuelve un dispose para
+ * limpiar.
+ */
+declare function bindPanelBehavior(root: ShadowRoot, opts?: BehaviorOptions): () => void;
+
+declare const PANEL_CSS = "\n:host {\n  --oks-btn-size: 55px;\n  --oks-bg: #000;\n  --oks-icon: #fff;\n  --oks-h-bg: #fff;\n  --oks-h-icon: #000;\n}\n.oks-access-wrapper {\n  position: fixed;\n  z-index: 9999999;\n  line-height: 1;\n}\n.oks-access-btn {\n  width: var(--oks-btn-size);\n  height: var(--oks-btn-size);\n  border-radius: 50%;\n  background: var(--oks-bg);\n  color: var(--oks-icon);\n  border: 2px solid #fff;\n  box-shadow: 0 4px 15px rgba(0,0,0,0.2);\n  display: flex;\n  align-items: center;\n  justify-content: center;\n  cursor: pointer;\n  transition: 0.2s;\n  padding: 0;\n}\n.oks-access-btn:hover {\n  background: var(--oks-h-bg);\n  color: var(--oks-h-icon);\n  transform: scale(1.1);\n}\n.oks-access-btn svg {\n  fill: currentColor;\n  display: block;\n  margin: 0 auto;\n  width: 60%;\n  height: 60%;\n}\n.oks-active-badge {\n  position: absolute;\n  top: -2px;\n  right: -2px;\n  width: 20px;\n  height: 20px;\n  background: #25D366;\n  border-radius: 50%;\n  border: 2px solid #fff;\n  display: flex;\n  align-items: center;\n  justify-content: center;\n  color: #fff;\n  opacity: 0;\n  pointer-events: none;\n}\n.oks-active-badge svg { width: 12px; height: 12px; }\n.oks-access-wrapper.has-active .oks-active-badge { opacity: 1; }\n\n.oks-access-panel {\n  position: fixed;\n  width: 340px;\n  max-height: 90vh;\n  background: #fff;\n  border-radius: 20px;\n  box-shadow: 0 20px 60px rgba(0,0,0,0.3);\n  z-index: 9999999;\n  display: flex;\n  flex-direction: column;\n  opacity: 0;\n  pointer-events: none;\n  transition: 0.2s;\n  border: 1px solid rgba(0,0,0,0.1);\n  font-family: system-ui, -apple-system, \"Segoe UI\", Roboto, sans-serif;\n  color: #333;\n}\n.oks-access-panel.is-open { opacity: 1; pointer-events: all; }\n.oks-access-header {\n  padding: 15px 20px;\n  border-bottom: 1px solid #eee;\n  display: flex;\n  justify-content: space-between;\n  align-items: center;\n}\n.oks-access-header h3 { margin: 0; font-size: 18px; color: #000; }\n.oks-access-close {\n  background: #f0f0f0;\n  color: #333;\n  border: 1px solid #ddd;\n  width: 44px;\n  height: 44px;\n  border-radius: 50%;\n  cursor: pointer;\n  display: flex;\n  align-items: center;\n  justify-content: center;\n  transition: 0.2s;\n  padding: 0;\n}\n.oks-access-close:hover { background: #e0e0e0; border-color: #ccc; }\n.oks-access-close svg { width: 24px; height: 24px; stroke-width: 2.5px; }\n.oks-access-content { padding: 0 20px 20px; overflow-y: auto; }\n.oks-access-title {\n  margin: 10px 0 5px;\n  font-size: 11px;\n  font-weight: 800;\n  text-transform: uppercase;\n  color: #888;\n}\n.oks-access-grid { display: grid; grid-template-columns: 1fr 1fr; gap: 8px; }\n.oks-access-opt {\n  background: #f9f9f9;\n  border: 2px solid #eee;\n  border-radius: 10px;\n  padding: 10px;\n  display: flex;\n  flex-direction: column;\n  align-items: center;\n  justify-content: center;\n  cursor: pointer;\n  min-height: 70px;\n  color: #333;\n  transition: 0.2s;\n  font: inherit;\n}\n.oks-access-opt.full-width { grid-column: span 2; }\n.oks-access-opt.is-active {\n  border-color: #000;\n  background: #fff;\n  box-shadow: 0 0 0 1px #000;\n}\n.oks-access-opt:hover { background: #000; color: #fff; border-color: #000; }\n.oks-icon { font-size: 28px; margin-bottom: 3px; display: block; line-height: 1; }\n.oks-icon svg { width: 24px; height: 24px; fill: currentColor; }\n.oks-label {\n  font-size: 11px;\n  font-weight: 700;\n  text-transform: uppercase;\n  text-align: center;\n  line-height: 1.2;\n}\n.oks-levels { display: flex; gap: 3px; height: 5px; width: 50%; margin-top: 5px; }\n.oks-levels span { flex: 1; background: #ddd; border-radius: 3px; }\n.oks-access-opt[data-level=\"1\"] .oks-levels span:nth-child(1),\n.oks-access-opt[data-level=\"2\"] .oks-levels span:nth-child(-n+2),\n.oks-access-opt[data-level=\"3\"] .oks-levels span:nth-child(-n+3),\n.oks-access-opt[data-level=\"4\"] .oks-levels span:nth-child(-n+4) { background: #000; }\n.oks-access-opt:hover .oks-levels span { background: #555; }\n.oks-access-footer {\n  padding: 12px 20px;\n  border-top: 1px solid #eee;\n  text-align: center;\n}\n.oks-access-reset {\n  width: 100%;\n  padding: 8px;\n  border: 2px solid #000;\n  color: #000;\n  background: transparent;\n  font-weight: 700;\n  cursor: pointer;\n  border-radius: 6px;\n  font-size: 12px;\n}\n.oks-access-reset:hover { background: #000; color: #fff; }\n.oks-access-branding { margin-top: 12px; font-size: 12px; color: #000; font-weight: 700; }\n.oks-access-branding a { color: #000; text-decoration: none; border-bottom: 1px dotted #000; }\n\n@media (max-width: 768px) {\n  .oks-access-panel {\n    width: 100%; height: 100%; max-height: 100%;\n    top: 0; left: 0; right: 0; bottom: 0;\n    border-radius: 0;\n  }\n  .oks-access-opt { min-height: 88px; padding: 14px 8px; }\n  .oks-icon svg { width: 30px; height: 30px; }\n  .oks-label { font-size: 12px; line-height: 1.3; }\n  .oks-access-grid { gap: 10px; }\n  .oks-access-content { padding: 0 16px 24px; }\n  .oks-access-title { font-size: 12px; margin: 14px 0 6px; }\n  .oks-access-reset { padding: 14px; font-size: 14px; }\n}\n";
+declare const EFFECT_CSS = "\nhtml.oks-colorblind-1 { filter: url('#oks-filter-protanopia'); }\nhtml.oks-colorblind-2 { filter: url('#oks-filter-deuteranopia'); }\nhtml.oks-colorblind-3 { filter: url('#oks-filter-tritanopia'); }\n\nbody.oks-zoom-1 *:not(header):not(header *):not(nav):not(nav *) { font-size: 1.05em !important; }\nbody.oks-zoom-2 *:not(header):not(header *):not(nav):not(nav *) { font-size: 1.10em !important; }\nbody.oks-zoom-3 *:not(header):not(header *):not(nav):not(nav *) { font-size: 1.15em !important; }\nbody.oks-zoom-4 *:not(header):not(header *):not(nav):not(nav *) { font-size: 1.20em !important; }\n\nbody.oks-lh-1 * { line-height: 1.6 !important; }\nbody.oks-lh-2 * { line-height: 1.9 !important; }\nbody.oks-lh-3 * { line-height: 2.2 !important; }\n\nbody.oks-a11y-font { font-family: Arial, sans-serif !important; }\n\nbody.oks-dyslexia * {\n  font-family: 'Comic Sans MS', 'Verdana', sans-serif !important;\n  letter-spacing: 0.05em !important;\n  word-spacing: 0.1em !important;\n  line-height: 1.6 !important;\n}\n\nbody.oks-a11y-hide img { opacity: 0 !important; visibility: hidden !important; }\nbody.oks-a11y-links a { text-decoration: underline !important; background: #ff0 !important; color: #000 !important; }\n\nbody.oks-align-1 * { text-align: left !important; }\nbody.oks-align-2 * { text-align: center !important; }\nbody.oks-align-3 * { text-align: right !important; }\n\nbody.oks-a11y-pause * { animation: none !important; transition: none !important; }\n\nbody.oks-ls-1 * { letter-spacing: 0.05em !important; }\nbody.oks-ls-2 * { letter-spacing: 0.10em !important; }\nbody.oks-ls-3 * { letter-spacing: 0.16em !important; }\n\nbody.oks-a11y-focus a:not(oksigenia-access-panel):not(oksigenia-access-panel *),\nbody.oks-a11y-focus button:not(oksigenia-access-panel):not(oksigenia-access-panel *),\nbody.oks-a11y-focus input,\nbody.oks-a11y-focus select,\nbody.oks-a11y-focus textarea {\n  outline: 2px dashed rgba(0, 95, 204, 0.45) !important;\n  outline-offset: 2px !important;\n}\nbody.oks-a11y-focus *:focus-visible {\n  outline: 3px solid #005fcc !important;\n  outline-offset: 3px !important;\n  box-shadow: 0 0 0 6px rgba(0, 95, 204, 0.25) !important;\n}\n\nbody.oks-a11y-contrast.oks-a11y-focus *:focus,\nbody.oks-a11y-contrast.oks-a11y-focus *:focus-visible {\n  outline-color: #0ff !important;\n  box-shadow: 0 0 0 6px rgba(0, 255, 255, 0.3) !important;\n}\n\n@media (pointer: fine) {\n  body.oks-big-cursor, body.oks-big-cursor a, body.oks-big-cursor button {\n    cursor: url(\"data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='48' height='48' viewBox='0 0 24 24'%3E%3Cpath d='M4 2L4 18L8 14L11 21L14 19.5L11 13L15.5 13Z' stroke='white' stroke-width='4' stroke-linejoin='round' fill='white'/%3E%3Cpath d='M4 2L4 18L8 14L11 21L14 19.5L11 13L15.5 13Z' fill='black'/%3E%3C/svg%3E\") 8 4, auto !important;\n  }\n}\n\nbody.oks-a11y-contrast,\nbody.oks-a11y-contrast *:not(oksigenia-access-panel):not(oksigenia-access-panel *) {\n  background-color: #000 !important;\n  color: #ff0 !important;\n  border-color: #ff0 !important;\n  text-shadow: none !important;\n  box-shadow: none !important;\n}\nbody.oks-a11y-contrast img { filter: grayscale(100%) contrast(120%) !important; }\nbody.oks-a11y-contrast a:not(oksigenia-access-panel *) { color: #0ff !important; text-decoration: underline !important; }\n\n.oks-overlay-effect {\n  position: fixed; top: 0; left: 0;\n  width: 100%; height: 100%;\n  pointer-events: none;\n  z-index: 999990;\n  display: none;\n  backdrop-filter: grayscale(100%);\n}\n.oks-overlay-effect.is-active { display: block; }\n\n.oks-reading-guide {\n  position: fixed; left: 0;\n  width: 100%; height: 50px;\n  background: rgba(255, 255, 0, 0.2);\n  border-top: 3px solid red;\n  border-bottom: 3px solid red;\n  pointer-events: none;\n  z-index: 2147483647;\n  display: none;\n  transform: translateY(-50%);\n}\nbody.oks-a11y-guide .oks-reading-guide { display: block; }\n";
+
+export { type BehaviorOptions, COLORBLIND_FILTERS_SVG, DEFAULT_STATE, EFFECT_CSS, type LocaleCode, PANEL_CSS, type PanelState, type Position, type Translation, type TriggerIcon, bindPanelBehavior, buildPanelHtml, getTranslation, isStateEmpty, loadState, positionCss, saveState, supportedLocales };