symbiote-ui 0.3.0-alpha.4

package/layout/LayoutRouter/LayoutRouter.js

@@ -0,0 +1,274 @@
+/**
+ * LayoutRouter — universal hash-based router for layout system
+ *
+ * Uses Symbiote PubSub named data context (ROUTER) to provide
+ * reactive routing across the application.
+ *
+ * URL format: #panel/subpath?param1=value&param2=value
+ *
+ * Two levels of query params:
+ * - **Global** (registered via registerGlobalParam): persist across section switches
+ * - **Section** (everything else): reset when navigating to a new section
+ *
+ * Usage in templates: {{ROUTER/panel}}, {{ROUTER/subpath}}, {{ROUTER/query}}
+ * Usage in code: this.$['ROUTER/panel'], this.sub('ROUTER/panel', cb)
+ * Global params: this.sub('ROUTER/globalParams', cb)
+ *
+ * @module symbiote-node/layout/LayoutRouter
+ */
+import { PubSub } from '@symbiotejs/symbiote/core/PubSub.js';
+
+const CTX = 'ROUTER';
+
+/** @type {Set<string>} Keys that persist across section switches */
+const _globalKeys = new Set();
+
+const routerCtx = PubSub.registerCtx(
+  {
+    panel: 'default',
+    subpath: '',
+    query: '',
+    globalParams: {},
+  },
+  CTX
+);
+
+/**
+ * Parse query string into object
+ * @param {string} str - Query string (without leading ?)
+ * @returns {Object<string, string>}
+ */
+export function parseQuery(str) {
+  if (!str) return {};
+  const result = {};
+  for (const pair of str.split('&')) {
+    const eqIdx = pair.indexOf('=');
+    if (eqIdx >= 0) {
+      result[decodeURIComponent(pair.substring(0, eqIdx))] = decodeURIComponent(
+        pair.substring(eqIdx + 1)
+      );
+    }
+  }
+  return result;
+}
+
+/**
+ * Build query string from key-value object
+ * @param {Object<string, string>} params
+ * @returns {string}
+ */
+export function buildQuery(params) {
+  const entries = Object.entries(params).filter(([, v]) => v !== '' && v != null);
+  if (entries.length === 0) return '';
+  return entries.map(([k, v]) => `${encodeURIComponent(k)}=${encodeURIComponent(v)}`).join('&');
+}
+
+/**
+ * Build full hash string from parts
+ * @param {string} panel
+ * @param {string} [subpath]
+ * @param {Object} [params]
+ * @returns {string}
+ */
+export function buildHash(panel, subpath, params) {
+  let hash = panel;
+  if (subpath) hash += '/' + subpath;
+  const q = params ? buildQuery(params) : '';
+  if (q) hash += '?' + q;
+  return hash;
+}
+
+/**
+ * Navigate to a new route — updates URL and PubSub context.
+ * Global params (registered via registerGlobalParam) are automatically
+ * carried over unless explicitly overridden or set to null.
+ * @param {string} panel - Master panel section ID
+ * @param {string} [subpath] - Sub-path (entity ID, etc.)
+ * @param {Object} [params] - Query parameters (overrides globals if specified)
+ */
+export function navigate(panel, subpath = '', params = {}) {
+  if (typeof location === 'undefined') return;
+
+  const currentQuery = parseQuery(routerCtx.read('query'));
+  const merged = {};
+  for (const key of _globalKeys) {
+    if (currentQuery[key] && params[key] === undefined) {
+      merged[key] = currentQuery[key];
+    }
+  }
+
+  for (const [k, v] of Object.entries(params)) {
+    if (v != null && v !== '') {
+      merged[k] = v;
+    } else {
+      delete merged[k];
+    }
+  }
+  const hash = buildHash(panel, subpath, merged);
+
+  history.pushState(null, '', location.pathname + '#' + hash);
+  syncFromHash();
+  if (typeof window !== 'undefined') {
+    window.dispatchEvent(new Event('hashchange'));
+  }
+}
+
+/**
+ * Update only query params of current route (keeps panel/subpath)
+ * Uses replaceState to avoid cluttering browser history
+ * @param {Object} params - Params to merge
+ */
+export function updateParams(params) {
+  if (typeof location === 'undefined') return;
+  const currentQuery = parseQuery(routerCtx.read('query'));
+  const merged = { ...currentQuery };
+  for (const [k, v] of Object.entries(params)) {
+    if (v === '' || v == null) {
+      delete merged[k];
+    } else {
+      merged[k] = v;
+    }
+  }
+  const query = buildQuery(merged);
+  const hash = buildHash(routerCtx.read('panel'), routerCtx.read('subpath'), merged);
+  history.replaceState(null, '', '#' + hash);
+  routerCtx.pub('query', query);
+  if (typeof window !== 'undefined') {
+    window.dispatchEvent(new Event('hashchange'));
+  }
+}
+
+/**
+ * Sync PubSub context from current URL hash
+ */
+function syncFromHash() {
+  const raw = location.hash.replace(/^#/, '') || 'default';
+
+  const qIdx = raw.indexOf('?');
+  const pathPart = qIdx >= 0 ? raw.substring(0, qIdx) : raw;
+  const queryPart = qIdx >= 0 ? raw.substring(qIdx + 1) : '';
+
+  const slashIdx = pathPart.indexOf('/');
+  const panel = slashIdx >= 0 ? pathPart.substring(0, slashIdx) : pathPart;
+  const subpath = slashIdx >= 0 ? pathPart.substring(slashIdx + 1) : '';
+
+  routerCtx.pub('panel', panel);
+  routerCtx.pub('subpath', subpath);
+  routerCtx.pub('query', queryPart);
+
+
+  if (_globalKeys.size > 0) {
+    const allParams = parseQuery(queryPart);
+    const globals = {};
+    for (const key of _globalKeys) {
+      if (allParams[key]) globals[key] = allParams[key];
+    }
+    routerCtx.pub('globalParams', globals);
+  }
+}
+
+/**
+ * Get current route state
+ * @returns {{ panel: string, subpath: string, query: string }}
+ */
+export function getRoute() {
+  return {
+    panel: routerCtx.read('panel'),
+    subpath: routerCtx.read('subpath'),
+    query: routerCtx.read('query'),
+  };
+}
+
+/**
+ * Set default panel (first section to show if hash is empty)
+ * @param {string} panel
+ */
+export function setDefaultPanel(panel) {
+  if (typeof location === 'undefined') return;
+  if (!location.hash || location.hash === '#') {
+    navigate(panel);
+  }
+}
+
+/**
+ * Register one or more param keys as global (persistent across section switches).
+ * Global params are automatically carried in navigate() and published
+ * via ROUTER/globalParams PubSub context.
+ * @param {...string} keys - Param names to register as global
+ */
+export function registerGlobalParam(...keys) {
+  keys.forEach((k) => _globalKeys.add(k));
+
+  if (typeof location !== 'undefined') {
+    const allParams = parseQuery(routerCtx.read('query'));
+    const globals = {};
+    for (const key of _globalKeys) {
+      if (allParams[key]) globals[key] = allParams[key];
+    }
+    routerCtx.pub('globalParams', globals);
+  }
+}
+
+/**
+ * Set a single global param value.
+ * Shorthand for registerGlobalParam + updateParams.
+ * @param {string} key
+ * @param {string|null} value - null removes the param
+ */
+export function setGlobalParam(key, value) {
+  _globalKeys.add(key);
+  updateParams({ [key]: value });
+}
+
+
+if (typeof location !== 'undefined' && typeof window !== 'undefined') {
+  syncFromHash();
+  window.addEventListener('hashchange', syncFromHash);
+}
+
+/**
+ * Generic search parameters builder
+ */
+export function getGraphSearchString(locationObj = typeof window !== 'undefined' ? window.location : {}) {
+  if (!locationObj || !locationObj.hash) return ''
+  const params = new URLSearchParams(locationObj.search || '')
+  const hashQuery = locationObj.hash.includes('?') ? locationObj.hash.split('?')[1] : ''
+  const hashParams = new URLSearchParams(hashQuery)
+  for (let [key, value] of hashParams) {
+    params.set(key, value)
+  }
+  return params.toString()
+}
+
+export function getGraphUrlParams(locationObj = typeof window !== 'undefined' ? window.location : {}) {
+  return new URLSearchParams(getGraphSearchString(locationObj))
+}
+
+export function parseGraphHash(hash = typeof window !== 'undefined' ? window.location.hash : '') {
+  if (!hash) return { path: '', params: new URLSearchParams() }
+  const [hashBase, queryStr] = hash.replace('#', '').split('?')
+  const hashParams = hashBase.split('/')
+  if (hashParams[0] === 'graph') hashParams.shift()
+  return {
+    path: hashParams.join('/'),
+    params: new URLSearchParams(queryStr || ''),
+  }
+}
+
+export function updateHashParam(key, value, locationObj = typeof window !== 'undefined' ? window.location : {}, historyObj = typeof history !== 'undefined' ? history : {}) {
+  if (!locationObj || !locationObj.hash) return
+  const [basePath, queryStr] = locationObj.hash.split('?')
+  const params = new URLSearchParams(queryStr || '')
+  if (value === null || value === undefined) {
+    params.delete(key)
+  } else {
+    params.set(key, value)
+  }
+  const newQuery = params.toString()
+  const newHash = newQuery ? `${basePath}?${newQuery}` : basePath
+  if (locationObj.hash === newHash) return
+  if (historyObj && typeof historyObj.replaceState === 'function') {
+    historyObj.replaceState(null, '', newHash)
+  }
+}
+

package/layout/LayoutRouter/SectionRegistry.js

@@ -0,0 +1,135 @@
+import * as LayoutTree from '../LayoutTree.js';
+
+export const SECTION_SCOPES = Object.freeze({
+  HOME: 'home',
+  PROJECT: 'project',
+  BOTH: 'both',
+});
+
+export class SectionRegistry {
+  constructor() {
+    this.sections = new Map();
+    this.layouts = new Map();
+  }
+
+  registerSection(id, { icon, label, order = 100, scope = SECTION_SCOPES.BOTH, layout } = {}) {
+    if (!id) throw new TypeError('Section id is required');
+    let normalizedScope = normalizeSectionScope(scope);
+    this.sections.set(id, { id, icon, label, order, scope: normalizedScope });
+    if (layout) this.layouts.set(id, layout);
+    return this.getSection(id);
+  }
+
+  getSection(id) {
+    return this.sections.get(id) || null;
+  }
+
+  getSections(filter = {}) {
+    let result = [...this.sections.values()];
+    if (filter.scope) {
+      result = result.filter((section) => sectionMatchesScope(section, filter.scope));
+    }
+    return result.sort((a, b) => a.order - b.order);
+  }
+
+  getHomeSections() {
+    return this.getSections({ scope: SECTION_SCOPES.HOME });
+  }
+
+  getProjectSections() {
+    return this.getSections({ scope: SECTION_SCOPES.PROJECT });
+  }
+
+  getSectionsForScope(projectIdOrScope) {
+    let scope = projectIdOrScope === SECTION_SCOPES.HOME || projectIdOrScope === SECTION_SCOPES.PROJECT
+      ? projectIdOrScope
+      : projectIdOrScope
+        ? SECTION_SCOPES.PROJECT
+        : SECTION_SCOPES.HOME;
+    return this.getSections({ scope });
+  }
+
+  getLayout(id) {
+    let layout = this.layouts.get(id);
+    return typeof layout === 'function' ? layout() : null;
+  }
+
+  hasSection(id) {
+    return this.sections.has(id);
+  }
+
+  clear() {
+    this.sections.clear();
+    this.layouts.clear();
+  }
+}
+
+export function createSectionRegistry() {
+  return new SectionRegistry();
+}
+
+export function normalizeSectionScope(scope = SECTION_SCOPES.BOTH) {
+  if (scope === SECTION_SCOPES.HOME || scope === SECTION_SCOPES.PROJECT || scope === SECTION_SCOPES.BOTH) {
+    return scope;
+  }
+  return SECTION_SCOPES.BOTH;
+}
+
+export function sectionMatchesScope(section, scope) {
+  let normalized = normalizeSectionScope(scope);
+  return section?.scope === normalized || section?.scope === SECTION_SCOPES.BOTH;
+}
+
+export function withGlobalPanel(layoutFn, panelType, {
+  direction = 'horizontal',
+  ratio = 0.65,
+  collapsed = true,
+  global = true,
+  panelState = {},
+} = {}) {
+  return () => {
+    let main = layoutFn();
+    let panel = LayoutTree.createPanel(panelType, panelState);
+    panel.global = global;
+    panel.collapsed = collapsed;
+    return LayoutTree.createSplit(direction, main, panel, ratio);
+  };
+}
+
+const defaultRegistry = createSectionRegistry();
+
+export function registerSection(id, options) {
+  return defaultRegistry.registerSection(id, options);
+}
+
+export function getSection(id) {
+  return defaultRegistry.getSection(id);
+}
+
+export function getSections(filter) {
+  return defaultRegistry.getSections(filter);
+}
+
+export function getHomeSections() {
+  return defaultRegistry.getHomeSections();
+}
+
+export function getProjectSections() {
+  return defaultRegistry.getProjectSections();
+}
+
+export function getSectionsForScope(projectIdOrScope) {
+  return defaultRegistry.getSectionsForScope(projectIdOrScope);
+}
+
+export function getLayout(id) {
+  return defaultRegistry.getLayout(id);
+}
+
+export function hasSection(id) {
+  return defaultRegistry.hasSection(id);
+}
+
+export function clearSections() {
+  defaultRegistry.clear();
+}

package/layout/LayoutRouter/routerSync.js

@@ -0,0 +1,250 @@
+/**
+ * routerSync — bidirectional URL ↔ component state sync
+ *
+ * Maps URL query params to component init$ properties and vice versa.
+ * Only syncs when the component's panel is active.
+ *
+ * Supports two mapping formats:
+ *
+ * Simple:  { componentProp: 'urlParam' }
+ * Extended: { componentProp: { param: 'urlParam', default: 'all', type: 'number' } }
+ *
+ * @example
+ * // Simple format:
+ * syncWithRouter(this, 'jobs', {
+ *   filterStatus: 'status',
+ *   filterRegion: 'region',
+ * });
+ *
+ * // Extended format:
+ * syncWithRouter(this, 'jobs', {
+ *   filterStatus: { param: 'status', default: 'all' },
+ *   currentPage: { param: 'page', default: 1, type: 'number' },
+ * });
+ *
+ * @module symbiote-node/layout/LayoutRouter/routerSync
+ */
+import { parseQuery, updateParams } from './LayoutRouter.js';
+
+/**
+ * Normalize mapping entry to { param, defaultVal, type }
+ * @param {string | { param: string, default?: *, type?: string }} entry
+ * @returns {{ param: string, defaultVal: *, type: string }}
+ */
+function normalizeMapping(entry) {
+  if (typeof entry === 'string') {
+    return { param: entry, defaultVal: undefined, type: 'string' };
+  }
+  return {
+    param: entry.param,
+    defaultVal: entry.default,
+    type: entry.type ?? 'string',
+  };
+}
+
+/**
+ * Cast value to the target type
+ * @param {string} value
+ * @param {string} type
+ * @returns {*}
+ */
+function castValue(value, type) {
+  if (type === 'number') return Number(value);
+  if (type === 'boolean') return value === 'true';
+  return value;
+}
+
+/**
+ * Sync component state with router URL params
+ *
+ * @param {import('@symbiotejs/symbiote').default} component - Symbiote component
+ * @param {string} panelName - Panel this component belongs to
+ * @param {Object<string, string | { param: string, default?: *, type?: string }>} mapping
+ */
+export function syncWithRouter(component, panelName, mapping) {
+  let syncing = false;
+
+
+  let normalizedMap = {};
+  for (const [prop, entry] of Object.entries(mapping)) {
+    normalizedMap[prop] = normalizeMapping(entry);
+  }
+
+  /**
+   * Read URL params into component state
+   */
+  function readFromURL() {
+    if (syncing) return;
+    syncing = true;
+    let query = parseQuery(component.$['ROUTER/query']);
+    for (const [prop, { param, defaultVal, type }] of Object.entries(normalizedMap)) {
+      let rawValue = query[param];
+      if (rawValue !== undefined) {
+        let val = castValue(rawValue, type);
+        if (component.$[prop] !== val) {
+          component.$[prop] = val;
+        }
+      } else if (defaultVal !== undefined) {
+
+        if (component.$[prop] !== defaultVal) {
+          component.$[prop] = defaultVal;
+        }
+      }
+    }
+    syncing = false;
+  }
+
+  /**
+   * Write component state to URL params
+   * @param {string} prop - Changed property name
+   */
+  function writeToURL(prop) {
+    if (syncing) return;
+    if (component.$['ROUTER/panel'] !== panelName) return;
+    syncing = true;
+    let { param, defaultVal } = normalizedMap[prop];
+    let value = component.$[prop];
+
+    if (value === defaultVal) {
+      updateParams({ [param]: '' });
+    } else {
+      updateParams({ [param]: String(value) });
+    }
+    syncing = false;
+  }
+
+
+  component.sub('ROUTER/panel', (panel) => {
+    if (panel === panelName) {
+      readFromURL();
+    }
+  });
+
+
+  component.sub('ROUTER/query', () => {
+    if (component.$['ROUTER/panel'] !== panelName) return;
+    readFromURL();
+  });
+
+
+  for (const prop of Object.keys(normalizedMap)) {
+    component.sub(prop, () => {
+      if (component.$['ROUTER/panel'] === panelName) {
+        writeToURL(prop);
+      }
+    });
+  }
+
+
+  if (component.$['ROUTER/panel'] === panelName) {
+    readFromURL();
+  }
+}
+
+/**
+ * setupPanelRouting — high-level panel routing setup
+ *
+ * Centralizes all routing logic for a panel:
+ * - Panel activation (onActivate callback)
+ * - List/detail switching via ROUTER/subpath
+ * - Tab sync via ?tab= query param
+ *
+ * Convention:
+ *   #panel               → list view, default tab
+ *   #panel?tab=groups    → list view, groups tab
+ *   #panel/{id}          → detail view
+ *
+ * Component requirements:
+ *   - ref="listWrap"     → container for list view (hidden when detail)
+ *   - <detail-component> → detail view element (hidden when list)
+ *   - $.activeTab        → tab state property (if tabs configured)
+ *
+ * @param {import('@symbiotejs/symbiote').default} component
+ * @param {string} panelName - Panel section ID (e.g. 'users')
+ * @param {Object} config
+ * @param {string[]} [config.tabs] - Tab names, first is default
+ * @param {{ component: string, loadMethod: string }} [config.detail] - Detail view config
+ * @param {Function} [config.onActivate] - Called when panel becomes active (list mode)
+ * @param {Object} [config.syncParams] - Additional params to sync via syncWithRouter
+ *
+ * @example
+ * renderCallback() {
+ *   setupPanelRouting(this, 'users', {
+ *     tabs: ['users', 'groups'],
+ *     detail: { component: 'user-detail-view', loadMethod: 'loadUser' },
+ *     onActivate: () => this.#loadData(),
+ *   });
+ * }
+ */
+export function setupPanelRouting(component, panelName, config = {}) {
+  let { tabs, detail, onActivate, syncParams } = config;
+
+
+  if (tabs && tabs.length > 0) {
+    let defaultTab = tabs[0];
+    syncWithRouter(component, panelName, {
+      activeTab: { param: 'tab', default: defaultTab },
+      ...(syncParams || {}),
+    });
+  } else if (syncParams) {
+    syncWithRouter(component, panelName, syncParams);
+  }
+
+  /**
+   * Check and apply list/detail mode based on ROUTER/subpath
+   */
+  function checkDetailMode() {
+    if (component.$['ROUTER/panel'] !== panelName) return;
+
+    let subpath = component.$['ROUTER/subpath'];
+    let listWrap = component.ref?.listWrap;
+    let isDetail = !!(detail && subpath);
+
+
+    component.toggleAttribute('data-detail', isDetail);
+
+    if (isDetail) {
+
+      if (listWrap) listWrap.hidden = true;
+
+      let detailEl = component.querySelector(detail.component);
+      if (detailEl) {
+        detailEl.hidden = false;
+        if (typeof detailEl[detail.loadMethod] === 'function') {
+          detailEl[detail.loadMethod](subpath);
+        }
+      }
+    } else {
+
+      if (listWrap) listWrap.hidden = false;
+
+      if (detail) {
+        let detailEl = component.querySelector(detail.component);
+        if (detailEl) detailEl.hidden = true;
+      }
+
+      if (onActivate) onActivate();
+    }
+  }
+
+
+  component.sub('ROUTER/panel', (panel) => {
+    if (panel === panelName) {
+      checkDetailMode();
+    }
+  });
+
+
+  if (detail) {
+    component.sub('ROUTER/subpath', () => {
+      if (component.$['ROUTER/panel'] === panelName) {
+        checkDetailMode();
+      }
+    });
+  }
+
+
+  if (component.$['ROUTER/panel'] === panelName) {
+    checkDetailMode();
+  }
+}