feat(market): shared web app manifest builder, back to parentHref through history only when it is the previous entry, backToPrevious option

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Amiram_se 2026-10-10 12:19:43 +04:00
parent 3e0cf9628d
commit 92a5e5410d
16 changed files with 181 additions and 45 deletions

View File

@ -0,0 +1,37 @@
import type { MetadataRoute } from 'next';
import { ROUTES } from '../navigation/navigation';
import {
MANIFEST_BACKGROUND_COLOR,
MANIFEST_ICONS,
MANIFEST_THEME_COLOR,
} from './constants';
import type { ManifestArgs } from './types';
/**
* The web app manifest for each app's `app/manifest.ts`. Both apps serve one origin, so they serve
* this same manifest (0053). The installed app opens on خانه, which sends a guest to login and a
* creator to their channel, so it never flashes the landing; `id` keeps the installed app's
* identity if `start_url` changes.
*/
export function buildManifest({
name,
description,
lang,
dir,
}: ManifestArgs): MetadataRoute.Manifest {
return {
id: '/',
name,
short_name: name,
description,
lang,
dir,
start_url: ROUTES.home,
scope: '/',
display: 'standalone',
background_color: MANIFEST_BACKGROUND_COLOR,
theme_color: MANIFEST_THEME_COLOR,
icons: [...MANIFEST_ICONS],
};
}

View File

@ -0,0 +1,18 @@
/**
* The light theme's `--bg-page` and `--action-primary` in island `theme.css`. The manifest can't
* read CSS variables, so a change there changes these too.
*/
export const MANIFEST_BACKGROUND_COLOR = '#f4f6f9';
export const MANIFEST_THEME_COLOR = '#533afd';
/** Placeholders until the brand mark exists; each app's `apple-icon.png` covers iOS. */
export const MANIFEST_ICONS = [
{ src: '/pwa/icon-192.png', sizes: '192x192', type: 'image/png' },
{ src: '/pwa/icon-512.png', sizes: '512x512', type: 'image/png' },
{
src: '/pwa/icon-maskable-512.png',
sizes: '512x512',
type: 'image/png',
purpose: 'maskable',
},
] as const;

View File

@ -0,0 +1,4 @@
import 'server-only';
export { buildManifest } from './build-manifest';
export type { ManifestArgs } from './types';

View File

@ -0,0 +1,8 @@
/** The manifest's text, in the app's one locale. */
export type ManifestArgs = {
/** «لومینا»: the name and the short name. */
name: string;
description: string;
lang: string;
dir: 'rtl' | 'ltr';
};

View File

@ -13,11 +13,33 @@ export const backTargetStore = createStore<{ target: BackTarget | null }>()(
);
/**
* Whether the page has a page of this site behind it in the tab's history. The Navigation API
* lists only this site's entries in a row, so a page opened from a link, a notification, another
* site or the bank has none; without it, any history counts.
* The key of the previous history entry when back should return to it (0057): `parentHref` itself,
* or, with `toPrevious`, any page of this site. The Navigation API lists only this site's entries,
* so a page opened from a link, a notification, another site or the bank has none; without the
* API there is none either, and back opens `parentHref`.
*/
export function hasInAppHistory(): boolean {
const { navigation } = window as { navigation?: { canGoBack: boolean } };
return navigation ? navigation.canGoBack : window.history.length > 1;
export function previousEntryKey(
parentHref: string,
toPrevious: boolean,
): string | undefined {
if (!('navigation' in window)) return undefined;
const current = navigation.currentEntry;
if (!current || current.index < 1) return undefined;
const previous = navigation.entries()[current.index - 1];
if (!previous?.url) return undefined;
if (toPrevious) return previous.key;
const from = new URL(previous.url).pathname;
const to = new URL(parentHref, window.location.href).pathname;
return from === to ? previous.key : undefined;
}
/**
* Goes back to the entry `previousEntryKey` found. By key, so a second press before the first lands
* goes to the same page, never further or out of the site.
*/
export function traverseTo(key: string): void {
const { committed, finished } = navigation.traverseTo(key);
// A newer navigation interrupts it, which is no error.
committed?.catch(() => undefined);
finished?.catch(() => undefined);
}

View File

@ -17,8 +17,9 @@ const DESK_BACK_CLASS =
/**
* «بازگشت» on desktop (R14): its own row at the top of a pushed page's column, above the page's
* title. Every page opened from another page has it (an installed app has no browser back); tab
* roots don't. Back goes to the page behind it on this site, or the page's `parentHref` when it was
* opened on its own; a fixed `href` (an auth step, the payment result's channel) is a link.
* roots don't. It links to the page's parent and goes back through history when the parent is the
* page behind (0057); a fixed `href` (an auth step, the payment result's subscriptions) is a plain
* link.
*/
export function DeskBack({ label, ...options }: DeskBackProps) {
const { t } = useTranslation();
@ -41,6 +42,7 @@ export function DeskBack({ label, ...options }: DeskBackProps) {
<FlexBox
tag={NextLink}
href={action.href}
onNavigate={action.onNavigate}
alignItems="items-center"
gap="gap-1"
className={DESK_BACK_CLASS}

View File

@ -8,8 +8,8 @@ import type { DesktopPageTitleProps } from './types';
/**
* A pushed page's heading on desktop, at the top of its column (U9 ۹.۱, S5 ۲.۱): «بازگشت» on its
* own row (R14), then the page's name. Back returns where the person came from on this site, or
* to the page's parent (home by default) for a page opened on its own.
* own row (R14), then the page's name. Back goes to the page's parent (home by default), through
* history when it is the page behind (0057).
*/
export function DesktopPageTitle({ title, ...back }: DesktopPageTitleProps) {
return (

View File

@ -37,8 +37,8 @@ const LOGIN_LINK_CLASS =
* since most visitors are guests. A creator's brand goes to their own channel, a guest's to the
* landing.
*
* Every page opened from another page has back (R14): to the page behind it on this site, or to
* `parentHref` (home by default) when it was opened on its own; `backHref` is a fixed target.
* Every page opened from another page has back (R14): to `parentHref` (home by default), through
* history when it is the page behind (0057); `backHref` is a fixed target.
* The connection bar draws under the bar, in the same sticky box.
*/
export function MobileTopBar({
@ -49,6 +49,7 @@ export function MobileTopBar({
back = true,
backHref,
parentHref,
backToPrevious,
previewTitle,
}: MobileTopBarProps) {
const { t } = useTranslation();
@ -79,6 +80,7 @@ export function MobileTopBar({
label={t('nav.back')}
href={backHref}
parentHref={parentHref}
backToPrevious={backToPrevious}
onBack={onBack}
/>
)}

View File

@ -6,9 +6,9 @@ import { useBack } from '../../../hooks/use-back';
import type { BackButtonProps } from '../types';
/**
* The bar's back (R14): to the page behind it on this site, or the page's parent when it was
* opened on its own (a link, a notification). A fixed `href` is a link; a page that may lose work
* passes `onBack` and asks first.
* The bar's back (R14, 0057): a link to the page's parent that goes back through history when the
* parent is the page behind. A fixed `href` is a plain link; a page that may lose work passes
* `onBack` and asks first.
*/
export function BackButton({ label, ...options }: BackButtonProps) {
const action = useBack(options);
@ -18,6 +18,7 @@ export function BackButton({ label, ...options }: BackButtonProps) {
icon="chevron-right"
label={label}
href={action.href}
onNavigate={action.onNavigate}
/>
) : (
<Button

View File

@ -19,8 +19,10 @@ type PushedBarProps = {
back?: boolean;
/** A fixed back target, followed whatever the history: the previous step, the paid channel. */
backHref?: BackOptions['href'];
/** Where back goes when the page was opened on its own (a link, a notification); home by default. */
/** The page's parent: back returns to it through history when it is behind, else opens it. */
parentHref?: BackOptions['parentHref'];
/** Reached from several places: back returns to any page of this site behind it. */
backToPrevious?: BackOptions['backToPrevious'];
/** The title while the page is in the creator's preview (`?preview`): «پیش‌نمایش پست». */
previewTitle?: string;
};
@ -35,6 +37,7 @@ type TabBarProps = {
back?: never;
backHref?: never;
parentHref?: never;
backToPrevious?: never;
previewTitle?: never;
};

View File

@ -2,29 +2,55 @@
import { useRouter } from 'next/navigation';
import { hasInAppHistory } from '../back-target';
import { previousEntryKey, traverseTo } from '../back-target';
import type { BackAction, BackOptions } from '../types';
import { useDeclaredBackTarget } from './use-back-target';
import { useHomeHref } from './use-home-href';
/**
* What back does on a page (R14), for the mobile bar's back and the desktop «بازگشت». A page that
* may lose work asks first (`onBack`). A target a part declared, or the page's own `href`, is a
* link. Otherwise back returns to the page behind it on this site, and a page opened on its own
* (a link, a notification) goes to its `parentHref`, or home.
*/
export function useBack({ href, parentHref, onBack }: BackOptions): BackAction {
const router = useRouter();
type ParentOptions = Pick<BackOptions, 'parentHref' | 'backToPrevious'>;
/** The page's parent, and whether any page of this site behind it counts as the way back. */
function useParent({ parentHref, backToPrevious = false }: ParentOptions) {
const homeHref = useHomeHref();
return {
href: parentHref ?? homeHref,
// Home is a fallback, not a parent the page names.
toPrevious: backToPrevious || parentHref === undefined,
};
}
/**
* What back does on a page (R14, 0057), for the mobile bar's back and the desktop «بازگشت». A page
* that may lose work asks first (`onBack`). A target a part declared, or the page's own `href`, is
* a plain link. Otherwise back links to the parent, and a plain click goes back through history
* instead when the page behind is the parent (or, with `backToPrevious`, any page of this site),
* so it comes back as it was left.
*/
export function useBack({ href, onBack, ...options }: BackOptions): BackAction {
const parent = useParent(options);
const declared = useDeclaredBackTarget();
const target = declared ?? href;
if (target && !onBack) return { href: target };
if (onBack) return { onClick: onBack };
if (target) return { href: target };
return {
onClick: () => {
if (onBack) onBack();
else if (hasInAppHistory()) router.back();
else router.push(parentHref ?? homeHref);
href: parent.href,
onNavigate: (event) => {
const key = previousEntryKey(parent.href, parent.toPrevious);
if (key === undefined) return;
event.preventDefault();
traverseTo(key);
},
};
}
/** The same back from code, such as after a leave dialog: through history when it can, else the parent. */
export function useGoBack(options: ParentOptions): () => void {
const router = useRouter();
const parent = useParent(options);
return () => {
const key = previousEntryKey(parent.href, parent.toPrevious);
if (key === undefined) router.push(parent.href);
else traverseTo(key);
};
}

View File

@ -15,6 +15,7 @@ export {
SEARCH_ENABLED,
} from './constants';
export { useAuthRoutes } from './hooks/use-auth-routes';
export { useGoBack } from './hooks/use-back';
export { useBackTarget } from './hooks/use-back-target';
export { useDialogRoute } from './hooks/use-dialog-route';
export { useHomeHref } from './hooks/use-home-href';

View File

@ -24,28 +24,38 @@ export type AuthRoutes = {
export type NavTabName = 'home' | 'search' | 'dashboard' | 'channel';
/**
* Where a page's back goes (R14), given by the page or its template. Every page opened from
* Where a page's back goes (R14, 0057), given by the page or its template. Every page opened from
* another page has back, on mobile and desktop; tab roots have none.
*/
export type BackOptions = {
/**
* A fixed target, followed as a link whatever the history: the previous auth step, or the
* payment result's channel, with the bank behind it.
* payment result's subscriptions, with the bank behind it.
*/
href?: string;
/**
* Where back goes when no page of this site is behind it (opened from a link or a notification):
* the page's parent, such as a post's channel or an account page's حساب کاربری. Defaults to home.
* The page's parent, such as a post's channel or an account page's حساب کاربری. Back returns to
* it through history when it is the page behind, so it comes back as it was left; otherwise, as
* after a link, a notification or a form that moved on, it opens it. Defaults to home, which
* names no parent, so any page of this site behind counts.
*/
parentHref?: string;
/**
* The page is reached from several places, such as a post from خانه, search or a notification:
* back returns to any page of this site behind it, and opens `parentHref` only when there is none.
*/
backToPrevious?: boolean;
/** Back asks first, such as a composer with unsaved text. */
onBack?: () => void;
};
/** A link to a fixed target, or a press that goes back. */
/** Next.js Link's `onNavigate`: runs only for a plain click Next would route itself. */
type OnNavigate = (event: { preventDefault: () => void }) => void;
/** A link (to a fixed target, or to the parent, going back through history when it can), or a press. */
export type BackAction =
| { href: string; onClick?: never }
| { href?: never; onClick: () => void };
| { href: string; onNavigate?: OnNavigate; onClick?: never }
| { href?: never; onNavigate?: never; onClick: () => void };
/** How a dialog that intercepts a route (bear's `@modal`) leaves it (0023, C4 ۷.۳). */
export type DialogRoute = {

View File

@ -10,7 +10,7 @@ import {
DesktopPageTitle,
MobileTopBar,
ROUTES,
useHomeHref,
useGoBack,
useLeaveGuard,
} from '../../../../../../navigation';
import { CreatorProfileEditSkeleton } from './CreatorProfileEditSkeleton';
@ -29,10 +29,11 @@ import type { CreatorProfileEditProps, LeaveTarget } from './types';
export function CreatorProfileEdit({ layout }: CreatorProfileEditProps) {
const { t } = useTranslation('auth');
const router = useRouter();
const homeHref = useHomeHref();
const [isDirty, setIsDirty] = useState(false);
const [leaveTo, setLeaveTo] = useState<LeaveTarget | null>(null);
const parentHref = layout === 'mobile' ? ROUTES.account.root : homeHref;
// Desktop opens it from the account menu on any page, so it names no parent: home, as a fallback.
const parentHref = layout === 'mobile' ? ROUTES.account.root : undefined;
const goBack = useGoBack({ parentHref });
const requestLeave = useCallback((href: string) => setLeaveTo({ href }), []);
useLeaveGuard(isDirty, requestLeave);
@ -40,8 +41,7 @@ export function CreatorProfileEdit({ layout }: CreatorProfileEditProps) {
const leave = (target: LeaveTarget) => {
setLeaveTo(null);
if (target.href) router.push(target.href);
else if (window.history.length > 1) router.back();
else router.push(parentHref);
else goBack();
};
const onBack = isDirty ? () => setLeaveTo({}) : undefined;
const title = t('profile-edit.title');

View File

@ -10,8 +10,8 @@ import {
useAccountProfilePage,
} from '../../../../../../../features/account';
import { PartBoundary } from '../../../../../../error-boundaries';
import { hasInAppHistory } from '../../../../../../navigation/back-target';
import { DesktopPageTitle } from '../../../../../../navigation/components/desktop-page-title';
import { useGoBack } from '../../../../../../navigation/hooks/use-back';
import { MobileTopBar } from '../../../../../../navigation/components/mobile-top-bar';
import { ROUTES } from '../../../../../../navigation/navigation';
import { LeaveDialog } from './components/LeaveDialog';
@ -28,11 +28,11 @@ import type { InvestorProfileFormProps } from './types';
export function InvestorProfileForm({ layout }: InvestorProfileFormProps) {
const { t } = useTranslation('account');
const router = useRouter();
const goBack = useGoBack({ parentHref: ROUTES.account.root });
const page = useAccountProfilePage({
onLeave: ({ href }) => {
if (href) router.push(href);
else if (hasInAppHistory()) router.back();
else router.push(ROUTES.account.root);
else goBack();
},
});
const photo = useAccountPhotoPart();

View File

@ -3,6 +3,8 @@ import 'server-only';
// Public server-only API, exposed as the `/server` subpath. index.ts never imports this file.
// Server reads carry no session: only what is the same for every visitor is read here.
export { readOnServer } from './app/error-boundaries/server';
export { buildManifest } from './app/manifest/server';
export type { ManifestArgs } from './app/manifest/server';
export {
channelMetadata,
faqJsonLd,