Press n or j to go to the next uncovered block, b, p or k for the previous block.
| 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 | 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 9x 9x 5x 5x 5x 5x 4x 4x 4x 4x 5x 5x 5x 5x 5x 5x 5x 5x 5x 5x 5x 5x 10x 210x 10x 1x 4x 2x 2x 2x 2x 3x 3x 1x 3x 1x 3x 1x | /**
* storybookToolbar — the Storybook toolbar for Blong stories.
*
* Five choices, each a Storybook global, all persisted in `localStorage` so a
* reload keeps the state a reviewer left behind:
*
* - `backend` — where a story reads its data from: the in-memory fixture mock
* (`mock`), a live gateway over plain JSON-RPC (`jsonrpc`), or a live
* gateway with end-to-end encryption (`mle`). Only the realm/suite preview
* offers this item — `blong-browser`'s own component stories have no
* platform and therefore no adapter to point anywhere.
* - `role` — the role the live back end is reached with (`Admin`, `Manager`,
* `Guest`, …). The Storybook dev-server plugin turns it into a token, so
* the stories never see a login screen.
* - `theme`, `language`, `direction` — presentation. On the realm/suite path
* the platform owns `<Theme>`, so there is no prop to write to: these are
* applied to the app store instead, which `<Theme>` already prefers over its
* config (see `selection.direction` in `Theme.tsx`). They are useful
* precisely for stories that render components rather than the portal shell,
* because no story renders the portal menubar that carries the switchers.
*
* The items are declared here rather than in each `.storybook/preview.tsx` so
* that the realm previews, `blong-browser`'s own preview and the kukum
* template cannot drift; a preview only calls the factory.
*
* Storybook passes the current globals to a decorator whose position in the
* `decorators` array is *outside* the story's own decorator, so the effect that
* applies them runs last. That matters for `blong-browser`'s preview, whose
* `withDispatch` resets the store on every story.
*/
import {THEME_OPTIONS} from './components/Theme/themeRegistry.js';
import {useAppStore} from './state/appStore.js';
/** Key the toolbar remembers its choices under. */
export const STORYBOOK_CHOICES_KEY = 'blong.storybook';
/** Where a story reads its data. */
export type StorybookBackend = 'mock' | 'jsonrpc' | 'mle';
/** The presentation choices the toolbar drives. */
export type StorybookDirection = 'ltr' | 'rtl';
/** Every choice the toolbar carries, as read from the globals. */
export interface IBlongStorybookOptions {
backend?: StorybookBackend;
role?: string;
theme?: string;
language?: string;
direction?: StorybookDirection;
}
/** Options for {@link blongStorybookToolbar}. */
export interface IBlongStorybookToolbarOptions {
/**
* Offer the `backend` and `role` items. Defaults to `false`; a preview of
* a realm or suite passes `true` (its stories run on a platform with a
* backend adapter, so there is something to switch).
*/
backend?: boolean;
/**
* Roles the `role` item offers, in display order. Defaults to the roles
* the Storybook dev-server plugin found in `.blong_devrc`, falling back to
* the seeded test users (`Admin`, `Manager`, `Guest`).
*/
roles?: string[];
/** Languages the `language` item offers. Defaults to `en` and `bg`. */
languages?: string[];
}
const DEFAULT_BACKEND: StorybookBackend = 'mock';
/** `vela-blue` is the folder the default `compact`/`dark` theme maps to. */
const DEFAULT_THEME = 'vela-blue';
const DEFAULT_LANGUAGE = 'en';
const DEFAULT_DIRECTION: StorybookDirection = 'ltr';
const DEFAULT_ROLES = ['Admin', 'Manager', 'Guest'];
const DEFAULT_LANGUAGES = ['en', 'bg'];
const BACKEND_VALUES = ['mock', 'jsonrpc', 'mle'] as const;
const DIRECTION_VALUES = ['ltr', 'rtl'] as const;
const BACKENDS: {value: StorybookBackend; title: string; description: string}[] = [
{value: 'mock', title: 'Mock', description: 'In-memory fixture rows, no back end'},
{value: 'jsonrpc', title: 'Live (JSON-RPC)', description: 'Real gateway, plain JSON-RPC'},
{value: 'mle', title: 'Live (MLE)', description: 'Real gateway, end-to-end encrypted'},
];
/**
* Backend/role list injected by the Storybook dev-server plugin
* (`define: {__BLONG_STORYBOOK__: …}`). Absent when no back end was
* configured, which is why every read falls back to a default.
*/
interface IInjectedStorybookConfig {
roles?: string[];
target?: string;
}
function injectedConfig(): IInjectedStorybookConfig {
const injected = (globalThis as {__BLONG_STORYBOOK__?: IInjectedStorybookConfig})
.__BLONG_STORYBOOK__;
return injected && typeof injected === 'object' ? injected : {};
}
function storedChoices(): IBlongStorybookOptions {
Iif (typeof localStorage === 'undefined') return {};
try {
const raw = localStorage.getItem(STORYBOOK_CHOICES_KEY);
return raw ? (JSON.parse(raw) as IBlongStorybookOptions) : {};
} catch {
return {};
}
}
/**
* Remember the choices a decorator observed. Only the choices the app store
* does not already persist are written here (theme and direction live in
* `blong.theme`), so the toolbar and the portal's own theme switcher agree.
*/
export function writeStorybookChoices(options: IBlongStorybookOptions): void {
Iif (typeof localStorage === 'undefined') return;
try {
const {backend, role, language} = options;
localStorage.setItem(STORYBOOK_CHOICES_KEY, JSON.stringify({backend, role, language}));
} catch {
// Ignore storage failures (private mode, quota, …).
}
}
/**
* The theme the app's own switcher last persisted, if any. Read here so a
* story opens in the theme the rest of the portal is already showing.
*/
function storedThemeId(): string | undefined {
Iif (typeof localStorage === 'undefined') return undefined;
try {
const raw = localStorage.getItem('blong.theme');
const selection = raw ? (JSON.parse(raw) as {themeId?: unknown}) : {};
return typeof selection.themeId === 'string' ? selection.themeId : undefined;
} catch {
return undefined;
}
}
/**
* The globals a preview starts from. Storybook's own `?globals=` URL
* parameter outranks these, which is what makes a state scriptable.
*/
export function blongStorybookInitialGlobals(
options: IBlongStorybookToolbarOptions = {},
): Record<string, string> {
const stored = storedChoices();
const roles = options.roles ?? injectedConfig().roles ?? DEFAULT_ROLES;
const languages = options.languages ?? DEFAULT_LANGUAGES;
return {
...(options.backend
? {
backend: stored.backend ?? DEFAULT_BACKEND,
role: stored.role && roles.includes(stored.role) ? stored.role : roles[0],
}
: {}),
theme: storedThemeId() ?? stored.theme ?? DEFAULT_THEME,
language:
stored.language && languages.includes(stored.language)
? stored.language
: DEFAULT_LANGUAGE,
direction: DEFAULT_DIRECTION,
};
}
/**
* The `globalTypes` entry for the toolbar. `dynamicTitle` puts the current
* value in the toolbar button, so a screenshot shows which state it captured.
*/
export function blongStorybookGlobalTypes(
options: IBlongStorybookToolbarOptions = {},
): Record<string, unknown> {
const roles = options.roles ?? injectedConfig().roles ?? DEFAULT_ROLES;
const languages = options.languages ?? DEFAULT_LANGUAGES;
return {
...(options.backend
? {
backend: {
description: 'Where the story reads its data from',
toolbar: {
title: 'Backend',
icon: 'database' as const,
items: BACKENDS,
dynamicTitle: true,
},
},
role: {
description: 'Role the live back end is reached with',
toolbar: {
title: 'Role',
icon: 'user' as const,
items: roles.map(role => ({value: role, title: role})),
dynamicTitle: true,
},
},
}
: {}),
theme: {
description: 'Theme variant',
toolbar: {
title: 'Theme',
icon: 'paintbrush' as const,
items: THEME_OPTIONS.map(option => ({value: option.id, title: option.label})),
dynamicTitle: true,
},
},
language: {
description: 'Interface language',
toolbar: {
title: 'Language',
icon: 'globe' as const,
items: languages.map(language => ({value: language, title: language})),
dynamicTitle: true,
},
},
direction: {
description: 'Text direction',
toolbar: {
title: 'Direction',
icon: 'mirror' as const,
items: [
{value: 'ltr', title: 'LTR'},
{value: 'rtl', title: 'RTL'},
],
dynamicTitle: true,
},
},
};
}
/** `globalTypes` + `initialGlobals`, ready to spread into a preview. */
export function blongStorybookToolbar(options: IBlongStorybookToolbarOptions = {}): {
globalTypes: Record<string, unknown>;
initialGlobals: Record<string, string>;
} {
return {
globalTypes: blongStorybookGlobalTypes(options),
initialGlobals: blongStorybookInitialGlobals(options),
};
}
/** The subset of the Storybook context the toolbar reads. */
export interface IBlongStorybookContext {
globals?: Record<string, unknown>;
}
function asValue<T extends string>(value: unknown, allowed: readonly T[]): T | undefined {
return typeof value === 'string' && (allowed as readonly string[]).includes(value)
? (value as T)
: undefined;
}
/**
* Read the toolbar's choices out of the Storybook context and remember them.
*
* Typed by hand rather than with Storybook's `Decorator` so that this module
* (and the `./storybook` entry it is exported from) does not depend on the
* Storybook packages at build time.
*/
export function blongStorybookGlobals(context?: IBlongStorybookContext): IBlongStorybookOptions {
const globals = context?.globals ?? {};
const options: IBlongStorybookOptions = {
backend: asValue(globals.backend, BACKEND_VALUES),
role: typeof globals.role === 'string' ? globals.role : undefined,
theme: typeof globals.theme === 'string' ? globals.theme : undefined,
language: typeof globals.language === 'string' ? globals.language : undefined,
direction: asValue(globals.direction, DIRECTION_VALUES),
};
writeStorybookChoices(options);
return options;
}
/**
* The choices the reviewer actually changed — the globals that differ from the
* ones the preview started from.
*
* Only those are applied. A story may set its own `args.lang` or
* `parameters.theme` (the Validation story renders in Bulgarian that way), and
* the toolbar's *default* must not quietly override it: a reviewer who has not
* touched the toolbar has expressed no opinion about the presentation.
*/
export function changedStorybookGlobals(
options: IBlongStorybookOptions,
initial: Record<string, unknown>,
): IBlongStorybookOptions {
const changed: IBlongStorybookOptions = {};
if (options.theme && options.theme !== initial.theme) changed.theme = options.theme;
if (options.direction && options.direction !== initial.direction) {
changed.direction = options.direction;
}
if (options.language && options.language !== initial.language) {
changed.language = options.language;
}
return changed;
}
/**
* Write the presentation globals into the app store.
*
* Separate from the decorator so it can be unit-tested without a renderer, and
* *idempotent*: a no-op when the store already holds the wanted value, because
* `setTheme` persists to `localStorage` and re-writing it on every story would
* be noise.
*/
export function applyStorybookGlobals(
store: Pick<
ReturnType<typeof useAppStore.getState>,
'theme' | 'language' | 'setTheme' | 'setDirection' | 'setLanguage'
>,
options: IBlongStorybookOptions,
): void {
const {theme, direction, language} = options;
if (theme && store.theme.themeId !== theme) {
store.setTheme({...store.theme, themeId: theme});
}
if (direction && store.theme.direction !== direction) {
store.setDirection(direction);
}
if (language && store.language !== language) {
store.setLanguage(language);
}
}
|