@btst/stack 5.1.0 → 5.2.0

package/src/plugins/feature-flags/client/components/pages/flags-page.internal.tsx

@@ -0,0 +1,196 @@
+"use client";
+
+import { useState } from "react";
+import {
+	PermissionAccess,
+	usePluginOverrides,
+	usePluginSiteNavigation,
+} from "@btst/stack/context";
+import { featureFlagsPermissions } from "../../../permissions";
+import type { FeatureFlag } from "../../../types";
+import { useSuspenseFlags, useToggleFlag } from "../../hooks";
+import { FEATURE_FLAGS_PLUGIN_ID } from "../../constants";
+import type { FeatureFlagsPluginOverrides } from "../../overrides";
+import { FlagsPage as Page, Rollout } from "../shared";
+
+export function FlagsPage() {
+	const [search, setSearch] = useState("");
+	const [tag, setTag] = useState("");
+	const [includeArchived, setIncludeArchived] = useState(false);
+	const {
+		data: flags,
+		refetch,
+		isFetching,
+	} = useSuspenseFlags({ includeArchived });
+	const { Link, resolve } = usePluginSiteNavigation(FEATURE_FLAGS_PLUGIN_ID);
+	const { localization } = usePluginOverrides<FeatureFlagsPluginOverrides>(
+		FEATURE_FLAGS_PLUGIN_ID,
+	);
+	const tags = [...new Set(flags.flatMap((flag) => flag.tags))].sort();
+	const visible = flags.filter(
+		(flag) =>
+			(!tag || flag.tags.includes(tag)) &&
+			`${flag.name} ${flag.key} ${flag.description ?? ""}`
+				.toLowerCase()
+				.includes(search.toLowerCase()),
+	);
+	return (
+		<Page
+			title={localization?.title ?? "Feature flags"}
+			description="Control what's live. Roll out changes to the right audience."
+			action={
+				<Link className="ff-primary" href={resolve("feature-flags/new").href}>
+					{localization?.newFlag ?? "New flag"}
+				</Link>
+			}
+		>
+			<div className="ff-toolbar">
+				<label className="ff-search">
+					Find a flag
+					<input
+						type="search"
+						value={search}
+						onChange={(event) => setSearch(event.target.value)}
+						placeholder="Search name or key"
+					/>
+				</label>
+				<label>
+					Tag
+					<select value={tag} onChange={(event) => setTag(event.target.value)}>
+						<option value="">All tags</option>
+						{tags.map((value) => (
+							<option key={value}>{value}</option>
+						))}
+					</select>
+				</label>
+				<label className="ff-checkbox">
+					<input
+						type="checkbox"
+						checked={includeArchived}
+						onChange={(event) => setIncludeArchived(event.target.checked)}
+					/>
+					Show archived
+				</label>
+				<button
+					type="button"
+					disabled={isFetching}
+					onClick={() => void refetch()}
+				>
+					Refresh flags
+				</button>
+			</div>
+			<p className="ff-count">
+				{visible.length} {visible.length === 1 ? "flag" : "flags"}
+			</p>
+			{visible.length ? (
+				<ul className="ff-list" aria-label="Feature flags">
+					{visible.map((flag) => (
+						<FlagRow key={flag.key} flag={flag} />
+					))}
+				</ul>
+			) : (
+				<div className="ff-empty">
+					<h2>
+						{flags.length ? "No matching flags" : "Your first flag starts here"}
+					</h2>
+					<p>
+						{flags.length
+							? "Try another name, key, or tag."
+							: "Create a flag to control a feature without redeploying your app."}
+					</p>
+				</div>
+			)}
+		</Page>
+	);
+}
+
+function FlagRow({ flag }: { flag: FeatureFlag }) {
+	const toggle = useToggleFlag();
+	const { Link, resolve } = usePluginSiteNavigation(FEATURE_FLAGS_PLUGIN_ID);
+	const [error, setError] = useState("");
+	const change = async () => {
+		setError("");
+		try {
+			await toggle.mutateAsync({ key: flag.key, enabled: !flag.enabled });
+		} catch (caught) {
+			setError(
+				caught instanceof Error
+					? caught.message
+					: "The flag could not be changed. Try again.",
+			);
+		}
+	};
+	return (
+		<li className="ff-row" data-archived={!!flag.archivedAt}>
+			<div className="ff-identity">
+				<Link
+					href={resolve(`feature-flags/${flag.key}`).href}
+					className="ff-name"
+				>
+					{flag.name}
+				</Link>
+				<code>{flag.key}</code>
+				{flag.description && <p>{flag.description}</p>}
+				{flag.tags.length > 0 && (
+					<ul className="ff-tags" aria-label="Tags">
+						{flag.tags.map((tag) => (
+							<li key={tag}>{tag}</li>
+						))}
+					</ul>
+				)}
+			</div>
+			<div className="ff-audience">
+				{flag.type === "rollout" ? (
+					<Rollout percent={flag.rolloutPct ?? 0} />
+				) : (
+					<>
+						<span>
+							{flag.type === "segment" ? "Segment targeting" : "Boolean"}
+						</span>
+						<p>
+							{flag.type === "segment"
+								? `${flag.segments.length} targeting ${flag.segments.length === 1 ? "rule" : "rules"}`
+								: "Everyone when enabled"}
+						</p>
+					</>
+				)}
+			</div>
+			<div className="ff-row-actions">
+				{flag.archivedAt ? (
+					<span className="ff-muted">Archived</span>
+				) : (
+					<PermissionAccess
+						permission={featureFlagsPermissions.flags.toggle({ key: flag.key })}
+					>
+						<button
+							type="button"
+							className="ff-toggle"
+							role="switch"
+							aria-label={`Enable ${flag.name}`}
+							aria-checked={flag.enabled}
+							disabled={toggle.isPending}
+							onClick={() => void change()}
+						>
+							<span aria-hidden="true" />
+							{flag.enabled ? "Enabled" : "Disabled"}
+						</button>
+					</PermissionAccess>
+				)}
+				<PermissionAccess
+					permission={featureFlagsPermissions.evaluations.read({
+						key: flag.key,
+					})}
+				>
+					<Link href={resolve(`feature-flags/${flag.key}/log`).href}>
+						Evaluation log
+					</Link>
+				</PermissionAccess>
+			</div>
+			{error && (
+				<p role="alert" className="ff-error">
+					{error}
+				</p>
+			)}
+		</li>
+	);
+}

package/src/plugins/feature-flags/client/components/pages.tsx

@@ -0,0 +1,95 @@
+"use client";
+
+import { lazy, useEffect, useState, type ReactNode } from "react";
+import { ComposedRoute } from "@btst/stack/client/components";
+import { featureFlagsPermissions } from "../../permissions";
+import { FlagsError, FlagsLoading, FlagsNotFound } from "./shared";
+
+const Flags = lazy(() =>
+	import("./pages/flags-page.internal").then((module) => ({
+		default: module.FlagsPage,
+	})),
+);
+const Editor = lazy(() =>
+	import("./pages/edit-flag-page.internal").then((module) => ({
+		default: module.EditFlagPage,
+	})),
+);
+const Log = lazy(() =>
+	import("./pages/flag-detail-page.internal").then((module) => ({
+		default: module.FlagDetailPage,
+	})),
+);
+
+function BrowserPage({ children }: { children: ReactNode }) {
+	const [mounted, setMounted] = useState(false);
+	useEffect(() => setMounted(true), []);
+	return mounted ? children : <FlagsLoading />;
+}
+
+function FlagList() {
+	return (
+		<BrowserPage>
+			<Flags />
+		</BrowserPage>
+	);
+}
+function FlagEditor(props: { flagKey?: string }) {
+	return (
+		<BrowserPage>
+			<Editor {...props} />
+		</BrowserPage>
+	);
+}
+function FlagLog(props: { flagKey: string }) {
+	return (
+		<BrowserPage>
+			<Log {...props} />
+		</BrowserPage>
+	);
+}
+
+const boundary = {
+	ErrorComponent: FlagsError,
+	LoadingComponent: FlagsLoading,
+	NotFoundComponent: FlagsNotFound,
+	onError: (error: Error) => console.error("[btst/feature-flags]", error),
+};
+
+/** Protected dynamic flag list with loading and error boundaries. */
+export function FlagsPageComponent() {
+	return (
+		<ComposedRoute
+			{...boundary}
+			path="/feature-flags"
+			permission={featureFlagsPermissions.flags.read({})}
+			PageComponent={FlagList}
+		/>
+	);
+}
+/** Create or edit a flag definition. */
+export function EditFlagPageComponent({ flagKey }: { flagKey?: string }) {
+	return (
+		<ComposedRoute
+			{...boundary}
+			path={flagKey ? `/feature-flags/${flagKey}` : "/feature-flags/new"}
+			{...(flagKey
+				? { permission: featureFlagsPermissions.flags.read({ key: flagKey }) }
+				: {})}
+			PageComponent={FlagEditor}
+			props={{ flagKey }}
+		/>
+	);
+}
+/** Protected recent evaluations for a flag. */
+export function FlagDetailPageComponent({ flagKey }: { flagKey: string }) {
+	return (
+		<ComposedRoute
+			{...boundary}
+			path={`/feature-flags/${flagKey}/log`}
+			permission={featureFlagsPermissions.evaluations.read({ key: flagKey })}
+			PageComponent={FlagLog}
+			props={{ flagKey }}
+		/>
+	);
+}

package/src/plugins/feature-flags/client/components/shared.tsx

@@ -0,0 +1,94 @@
+"use client";
+
+import type { ReactNode } from "react";
+import type { FallbackProps } from "@btst/stack/client/components";
+
+export function FlagsPage({
+	title,
+	description,
+	action,
+	children,
+}: {
+	title: string;
+	description?: string;
+	action?: ReactNode;
+	children: ReactNode;
+}) {
+	return (
+		<section className="feature-flags-page">
+			<header className="ff-header">
+				<div>
+					<h1>{title}</h1>
+					{description && <p>{description}</p>}
+				</div>
+				{action}
+			</header>
+			{children}
+		</section>
+	);
+}
+
+export function FlagsLoading() {
+	return (
+		<section className="feature-flags-page" role="status">
+			<h1>Feature flags</h1>
+			<p>Loading flags…</p>
+		</section>
+	);
+}
+
+export function FlagsError({ resetErrorBoundary }: FallbackProps) {
+	return (
+		<section className="feature-flags-page" role="alert">
+			<h1>Feature flags unavailable</h1>
+			<p>Flags could not be loaded. Check your access and try again.</p>
+			<button type="button" onClick={resetErrorBoundary}>
+				Try again
+			</button>
+		</section>
+	);
+}
+
+export function FlagsNotFound({ message }: { message: string }) {
+	return (
+		<section className="feature-flags-page">
+			<h1>Flag not found</h1>
+			<p>{message}</p>
+		</section>
+	);
+}
+
+export function Field({
+	id,
+	label,
+	hint,
+	children,
+}: {
+	id: string;
+	label: string;
+	hint?: string;
+	children: ReactNode;
+}) {
+	return (
+		<div className="ff-field">
+			<label htmlFor={id}>{label}</label>
+			{children}
+			{hint && (
+				<p id={`${id}-hint`} className="ff-note">
+					{hint}
+				</p>
+			)}
+		</div>
+	);
+}
+
+export function Rollout({ percent }: { percent: number }) {
+	return (
+		<div className="ff-rollout">
+			<span>{percent}% rollout</span>
+			<meter aria-label="Rollout percentage" min={0} max={100} value={percent}>
+				{percent}%
+			</meter>
+		</div>
+	);
+}

package/src/plugins/feature-flags/client/constants.ts

@@ -0,0 +1,2 @@
+/** Canonical identifier for the feature flags plugin. */
+export const FEATURE_FLAGS_PLUGIN_ID = "featureFlags" as const;

package/src/plugins/feature-flags/client/hooks/index.tsx

@@ -0,0 +1,77 @@
+"use client";
+
+import { useEffect } from "react";
+import {
+	useIdentity,
+	useIdentitySourceGeneration,
+	useStack,
+} from "@btst/stack/context";
+import { createResource } from "@btst/stack/plugins/client/hooks";
+import { featureFlagsResources, type FlagListParams } from "../../query-keys";
+import type { FlagContext } from "../../types";
+import { FEATURE_FLAGS_PLUGIN_ID } from "../constants";
+
+const flags = createResource({
+	plugin: FEATURE_FLAGS_PLUGIN_ID,
+	resources: featureFlagsResources,
+});
+
+function useFlagPartition() {
+	const { identity, isPending, error } = useIdentity();
+	const generation = useIdentitySourceGeneration();
+	const { plugins } = useStack();
+	const api = plugins?.[FEATURE_FLAGS_PLUGIN_ID]?.api;
+	return {
+		identity,
+		generation,
+		isPending,
+		error: !!error,
+		endpoint: [api?.baseURL, api?.basePath],
+		headers: [...new Headers(api?.browserHeaders)],
+		credentials: api?.credentials,
+	};
+}
+
+/** Evaluate one flag for a context. Visible clients refresh every thirty seconds. */
+export function useFlag(key: string, context?: FlagContext) {
+	const partition = useFlagPartition();
+	const enabled = !!key && !partition.isPending && !partition.error;
+	const result = flags.flagValues.value.use([key, context, partition], {
+		enabled,
+	});
+	const { refetch } = result;
+	useEffect(() => {
+		if (!enabled) return;
+		const interval = setInterval(() => {
+			if (document.visibilityState === "visible") void refetch();
+		}, 30_000);
+		return () => clearInterval(interval);
+	}, [refetch, enabled]);
+	return result;
+}
+
+/** List flag definitions for management, partitioned by identity and transport. */
+export function useFlags(params: FlagListParams = {}) {
+	const partition = useFlagPartition();
+	return flags.featureFlags.list.use([params, partition], {
+		enabled: !partition.isPending && !partition.error,
+	});
+}
+
+/** Fetch management definitions through the route's suspense boundary. */
+export const useSuspenseFlags = (params: FlagListParams = {}) =>
+	flags.featureFlags.list.useSuspense([params, useFlagPartition()]);
+/** Fetch one editable flag definition. */
+export const useFlagDefinition = (key: string) =>
+	flags.featureFlags.detail.useSuspense([key, useFlagPartition()]);
+/** Fetch recent evaluations for a flag. */
+export const useFlagEvaluations = (key: string) =>
+	flags.flagEvaluations.list.useSuspense([key, useFlagPartition()]);
+/** Create a flag definition. */
+export const useCreateFlag = () => flags.featureFlags.create.use();
+/** Update a flag's name, targeting and tags. */
+export const useUpdateFlag = () => flags.featureFlags.update.use();
+/** Change a flag's live status. */
+export const useToggleFlag = () => flags.featureFlags.toggle.use();
+/** Archive a flag and stop evaluating it as enabled. */
+export const useArchiveFlag = () => flags.featureFlags.archive.use();

package/src/plugins/feature-flags/client/index.ts

@@ -0,0 +1,5 @@
+export {
+	featureFlagsClientPlugin,
+	type FeatureFlagsClientConfig,
+} from "./plugin";
+export type { FeatureFlagsPluginOverrides } from "./overrides";

package/src/plugins/feature-flags/client/overrides.ts

@@ -0,0 +1,5 @@
+/** Presentation choices for the feature flag management pages. */
+export interface FeatureFlagsPluginOverrides {
+	/** Override the management page title and create action. */
+	localization?: Partial<{ title: string; newFlag: string }>;
+}

package/src/plugins/feature-flags/client/plugin.tsx

@@ -0,0 +1,72 @@
+import { lazy, type ComponentType } from "react";
+import {
+	defineClientPlugin,
+	defineRoute,
+	defineRoutes,
+} from "@btst/stack/plugins/client";
+import { FEATURE_FLAGS_PLUGIN_ID } from "./constants";
+import type { FeatureFlagsPluginOverrides } from "./overrides";
+
+const Flags = lazy(() =>
+	import("./components/pages").then((module) => ({
+		default: module.FlagsPageComponent,
+	})),
+);
+const Editor = lazy(() =>
+	import("./components/pages").then((module) => ({
+		default: module.EditFlagPageComponent,
+	})),
+);
+const Log = lazy(() =>
+	import("./components/pages").then((module) => ({
+		default: module.FlagDetailPageComponent,
+	})),
+);
+
+/** Optional replacements for the built-in feature flag management pages. */
+export interface FeatureFlagsClientConfig {
+	/** Ejected or custom pages using the same routes. */
+	pageComponents?: {
+		flags?: ComponentType;
+		newFlag?: ComponentType;
+		editFlag?: ComponentType<{ params: { key: string } }>;
+		flagDetail?: ComponentType<{ params: { key: string } }>;
+	};
+}
+
+/** Runtime feature evaluation and dynamic administration routes. */
+export const featureFlagsClientPlugin = (
+	config: FeatureFlagsClientConfig = {},
+) =>
+	defineClientPlugin<FeatureFlagsPluginOverrides>()({
+		id: FEATURE_FLAGS_PLUGIN_ID,
+		resolve: () => ({
+			routes: () =>
+				defineRoutes(
+					{
+						flags: defineRoute("/feature-flags", {
+							page: Flags,
+							meta: () => meta("Feature flags"),
+						}),
+						newFlag: defineRoute("/feature-flags/new", {
+							page: () => <Editor />,
+							meta: () => meta("New flag"),
+						}),
+						editFlag: defineRoute("/feature-flags/:key", {
+							page: ({ params }) => <Editor flagKey={params.key} />,
+							meta: () => meta("Edit flag"),
+						}),
+						flagDetail: defineRoute("/feature-flags/:key/log", {
+							page: ({ params }) => <Log flagKey={params.key} />,
+							meta: () => meta("Flag evaluations"),
+						}),
+					},
+					{ pages: config.pageComponents },
+				),
+			sitemap: async () => [],
+		}),
+	});
+
+function meta(title: string) {
+	return [{ title }, { name: "robots", content: "noindex, nofollow" }];
+}