beez-ui 0.7.0 → 0.8.0

package/dist/lib/horizontal-swipe.js

@@ -0,0 +1,29 @@
+/**
+* Pure classification of a pointer drag into a horizontal swipe. Kept apart
+* from the DOM so thresholds are unit-testable and shared by any pager.
+*/
+export const HORIZONTAL_SWIPE_DIRECTION = {
+	next: "next",
+	previous: "previous"
+};
+/** Minimum horizontal travel, in CSS pixels, to count as a swipe. */
+const SWIPE_MIN_DISTANCE_PX = 60;
+/** Horizontal travel must dominate vertical travel by this ratio. */
+const SWIPE_HORIZONTAL_DOMINANCE_RATIO = 1.5;
+/** Slower drags read as reading/scrolling, not as a page flip. */
+const SWIPE_MAX_DURATION_MS = 800;
+/**
+* Decides whether a drag is a deliberate horizontal swipe. A leftward swipe
+* moves to the next page and a rightward one to the previous page, like
+* turning a calendar page.
+*
+* @param gesture - Pointer travel and duration.
+* @returns The swipe direction, or null when the drag is not a swipe.
+*/
+export function resolveHorizontalSwipe(gesture) {
+	const horizontalDistance = Math.abs(gesture.deltaX);
+	if (horizontalDistance < SWIPE_MIN_DISTANCE_PX || horizontalDistance < Math.abs(gesture.deltaY) * SWIPE_HORIZONTAL_DOMINANCE_RATIO || gesture.durationMs > SWIPE_MAX_DURATION_MS) {
+		return null;
+	}
+	return gesture.deltaX < 0 ? HORIZONTAL_SWIPE_DIRECTION.next : HORIZONTAL_SWIPE_DIRECTION.previous;
+}

package/dist/lib/in-app-browser.d.ts

@@ -0,0 +1,35 @@
+/** Detects in-app browsers and builds deep links that reopen a URL in the default browser. */
+export type InAppBrowserDetectionResult = {
+    isInAppBrowser: boolean;
+    isIos: boolean;
+    isAndroid: boolean;
+    isMercadoPago: boolean;
+};
+/**
+ * Classifies a user agent: in-app browsers (social, messaging and payment apps, iOS web views)
+ * often block sign-in popups or lose sessions, so callers can offer to continue elsewhere.
+ * Safe on the server: pass the request `User-Agent` header.
+ *
+ * @param userAgent - User agent string, or nothing when unknown.
+ * @returns Whether it is an in-app browser and which platform it runs on.
+ */
+export declare function detectInAppBrowser(userAgent: string | null | undefined): InAppBrowserDetectionResult;
+export declare const EXTERNAL_BROWSER_PLATFORM: {
+    readonly android: "android";
+    readonly ios: "ios";
+};
+export type ExternalBrowserPlatform = (typeof EXTERNAL_BROWSER_PLATFORM)[keyof typeof EXTERNAL_BROWSER_PLATFORM];
+type BuildExternalBrowserUrlInput = {
+    platform: ExternalBrowserPlatform;
+    targetHttpsUrl: string;
+};
+/**
+ * Builds a deep link that asks the OS to open the given https URL in the
+ * user's default external browser instead of the in-app browser.
+ *
+ * @param input - Target URL and detected platform.
+ * @returns A deep-link URL for iOS Safari or Android Chrome. Returns null when
+ *          the target URL does not use the https scheme.
+ */
+export declare function buildExternalBrowserUrl({ platform, targetHttpsUrl, }: BuildExternalBrowserUrlInput): string | null;
+export {};

package/dist/lib/in-app-browser.js

@@ -0,0 +1,80 @@
+/** Detects in-app browsers and builds deep links that reopen a URL in the default browser. */
+/** User-agent fragments of apps that open links in their own embedded browser. */
+const IN_APP_BROWSER_USER_AGENT_TOKENS = [
+	"MercadoPago",
+	"MercadoLibre",
+	"MLWebKit",
+	"FBAN",
+	"FBAV",
+	"Instagram",
+	"Line/",
+	"MicroMessenger",
+	"Twitter"
+];
+const IOS_DEVICE_TOKENS = [
+	"iPhone",
+	"iPad",
+	"iPod"
+];
+const ANDROID_DEVICE_TOKEN = "Android";
+const SAFARI_USER_AGENT_TOKEN = "Safari/";
+const IOS_MOBILE_USER_AGENT_TOKEN = "Mobile/";
+const MERCADO_PAGO_USER_AGENT_TOKENS = [
+	"MercadoPago",
+	"MercadoLibre",
+	"MLWebKit"
+];
+/**
+* Classifies a user agent: in-app browsers (social, messaging and payment apps, iOS web views)
+* often block sign-in popups or lose sessions, so callers can offer to continue elsewhere.
+* Safe on the server: pass the request `User-Agent` header.
+*
+* @param userAgent - User agent string, or nothing when unknown.
+* @returns Whether it is an in-app browser and which platform it runs on.
+*/
+export function detectInAppBrowser(userAgent) {
+	if (!userAgent) {
+		return {
+			isInAppBrowser: false,
+			isIos: false,
+			isAndroid: false,
+			isMercadoPago: false
+		};
+	}
+	const isIos = IOS_DEVICE_TOKENS.some((token) => userAgent.includes(token));
+	const isAndroid = userAgent.includes(ANDROID_DEVICE_TOKEN);
+	const isMercadoPago = MERCADO_PAGO_USER_AGENT_TOKENS.some((token) => userAgent.includes(token));
+	const hasInAppToken = IN_APP_BROWSER_USER_AGENT_TOKENS.some((token) => userAgent.includes(token));
+	const isIosWebView = isIos && userAgent.includes(IOS_MOBILE_USER_AGENT_TOKEN) && !userAgent.includes(SAFARI_USER_AGENT_TOKEN);
+	return {
+		isInAppBrowser: hasInAppToken || isIosWebView,
+		isIos,
+		isAndroid,
+		isMercadoPago
+	};
+}
+const HTTPS_PROTOCOL = "https://";
+const SAFARI_URL_SCHEME = "x-safari-https://";
+const CHROME_ANDROID_NAVIGATION_URL_PREFIX = "googlechrome://navigate?url=";
+export const EXTERNAL_BROWSER_PLATFORM = {
+	android: "android",
+	ios: "ios"
+};
+/**
+* Builds a deep link that asks the OS to open the given https URL in the
+* user's default external browser instead of the in-app browser.
+*
+* @param input - Target URL and detected platform.
+* @returns A deep-link URL for iOS Safari or Android Chrome. Returns null when
+*          the target URL does not use the https scheme.
+*/
+export function buildExternalBrowserUrl({ platform, targetHttpsUrl }) {
+	if (!targetHttpsUrl.startsWith(HTTPS_PROTOCOL)) {
+		return null;
+	}
+	const urlWithoutScheme = targetHttpsUrl.slice(HTTPS_PROTOCOL.length);
+	if (platform === EXTERNAL_BROWSER_PLATFORM.ios) {
+		return SAFARI_URL_SCHEME + urlWithoutScheme;
+	}
+	return CHROME_ANDROID_NAVIGATION_URL_PREFIX + encodeURIComponent(targetHttpsUrl);
+}

package/dist/lib/month-grid.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Pure, time-zone-free helpers for month calendars. Days are `YYYY-MM-DD` keys and months are
+ * `YYYY-MM` keys; the application decides which zone turns an instant into a day key.
+ */
+export declare const CALENDAR_WEEK_LENGTH = 7;
+/** First day of the week: 0 is Sunday, 1 is Monday. */
+export type CalendarWeekStart = 0 | 1;
+/** One cell of the month grid. */
+export interface MonthGridDay {
+    /** `YYYY-MM-DD` key of the cell. */
+    dateKey: string;
+    dayNumber: number;
+    /** False for padding days of the neighbour months. */
+    isCurrentMonth: boolean;
+}
+/**
+ * Builds the cells of a month grid, padding the first and last week with neighbour-month days.
+ * @param month - `YYYY-MM` month key.
+ * @param weekStartsOn - First day of the week; Monday by default.
+ * @returns Every cell of the grid, a multiple of seven.
+ */
+export declare function createMonthGridDays(month: string, weekStartsOn?: CalendarWeekStart): MonthGridDay[];
+/**
+ * Splits grid cells into rows of seven days.
+ * @param days - Cells returned by {@link createMonthGridDays}.
+ * @returns One array per week.
+ */
+export declare function splitCalendarWeeks<TDay>(days: readonly TDay[]): TDay[][];
+/**
+ * Indexes items by their day key, keeping input order within each day.
+ * @param items - Items, usually sorted by start.
+ * @param getDateKey - Reads the `YYYY-MM-DD` key of an item.
+ * @returns Record from day key to the items of that day.
+ */
+export declare function groupItemsByDateKey<TItem>(items: readonly TItem[], getDateKey: (item: TItem) => string): Record<string, TItem[]>;
+/**
+ * Moves a month key by a number of months.
+ * @param month - `YYYY-MM` month key.
+ * @param monthOffset - Months to add; negative values go back.
+ * @returns The resulting `YYYY-MM` key.
+ */
+export declare function shiftMonthKey(month: string, monthOffset: number): string;

package/dist/lib/month-grid.js

@@ -0,0 +1,74 @@
+/**
+* Pure, time-zone-free helpers for month calendars. Days are `YYYY-MM-DD` keys and months are
+* `YYYY-MM` keys; the application decides which zone turns an instant into a day key.
+*/
+export const CALENDAR_WEEK_LENGTH = 7;
+const MILLISECONDS_PER_DAY = 864e5;
+const DATE_KEY_LENGTH = 10;
+const MONTH_KEY_LENGTH = 7;
+const MONTH_KEY_PATTERN = /^(\d{4})-(0[1-9]|1[0-2])$/;
+/**
+* Parses a `YYYY-MM` key.
+* @param month - Month key.
+* @returns The year and zero-based month index.
+* @throws {RangeError} When the key is not a valid `YYYY-MM` month.
+*/
+function parseMonthKey(month) {
+	const match = MONTH_KEY_PATTERN.exec(month);
+	if (!match) throw new RangeError(`month-grid:parseMonthKey expected a YYYY-MM month, received "${month.slice(0, 20)}"`);
+	return {
+		year: Number(match[1]),
+		monthIndex: Number(match[2]) - 1
+	};
+}
+/**
+* Builds the cells of a month grid, padding the first and last week with neighbour-month days.
+* @param month - `YYYY-MM` month key.
+* @param weekStartsOn - First day of the week; Monday by default.
+* @returns Every cell of the grid, a multiple of seven.
+*/
+export function createMonthGridDays(month, weekStartsOn = 1) {
+	const { year, monthIndex } = parseMonthKey(month);
+	const monthStartTime = Date.UTC(year, monthIndex, 1);
+	const daysInMonth = new Date(Date.UTC(year, monthIndex + 1, 0)).getUTCDate();
+	const leadingDays = (new Date(monthStartTime).getUTCDay() + CALENDAR_WEEK_LENGTH - weekStartsOn) % CALENDAR_WEEK_LENGTH;
+	const totalCells = Math.ceil((leadingDays + daysInMonth) / CALENDAR_WEEK_LENGTH) * CALENDAR_WEEK_LENGTH;
+	const firstCellTime = monthStartTime - leadingDays * MILLISECONDS_PER_DAY;
+	return Array.from({ length: totalCells }, (_, dayIndex) => {
+		const date = new Date(firstCellTime + dayIndex * MILLISECONDS_PER_DAY);
+		return {
+			dateKey: date.toISOString().slice(0, DATE_KEY_LENGTH),
+			dayNumber: date.getUTCDate(),
+			isCurrentMonth: date.getUTCMonth() === monthIndex
+		};
+	});
+}
+/**
+* Splits grid cells into rows of seven days.
+* @param days - Cells returned by {@link createMonthGridDays}.
+* @returns One array per week.
+*/
+export function splitCalendarWeeks(days) {
+	return Array.from({ length: Math.ceil(days.length / CALENDAR_WEEK_LENGTH) }, (_, weekIndex) => days.slice(weekIndex * CALENDAR_WEEK_LENGTH, (weekIndex + 1) * CALENDAR_WEEK_LENGTH));
+}
+/**
+* Indexes items by their day key, keeping input order within each day.
+* @param items - Items, usually sorted by start.
+* @param getDateKey - Reads the `YYYY-MM-DD` key of an item.
+* @returns Record from day key to the items of that day.
+*/
+export function groupItemsByDateKey(items, getDateKey) {
+	const groupedItems = {};
+	for (const item of items) (groupedItems[getDateKey(item)] ??= []).push(item);
+	return groupedItems;
+}
+/**
+* Moves a month key by a number of months.
+* @param month - `YYYY-MM` month key.
+* @param monthOffset - Months to add; negative values go back.
+* @returns The resulting `YYYY-MM` key.
+*/
+export function shiftMonthKey(month, monthOffset) {
+	const { year, monthIndex } = parseMonthKey(month);
+	return new Date(Date.UTC(year, monthIndex + monthOffset, 1)).toISOString().slice(0, MONTH_KEY_LENGTH);
+}

package/dist/lib/name-initials.d.ts

@@ -0,0 +1,7 @@
+/** Builds avatar initials from display names, shared by account and member avatars. */
+/**
+ * Builds up to two uppercase initials from a display name, ignoring repeated spaces.
+ * @param name - Display name, possibly blank.
+ * @returns The initials, or an empty string for a blank name.
+ */
+export declare function getNameInitials(name: string): string;

package/dist/lib/name-initials.js

@@ -0,0 +1,11 @@
+/** Builds avatar initials from display names, shared by account and member avatars. */
+const NAME_PART_SEPARATOR = /\s+/;
+const MAX_INITIALS = 2;
+/**
+* Builds up to two uppercase initials from a display name, ignoring repeated spaces.
+* @param name - Display name, possibly blank.
+* @returns The initials, or an empty string for a blank name.
+*/
+export function getNameInitials(name) {
+	return name.trim().split(NAME_PART_SEPARATOR).filter(Boolean).slice(0, MAX_INITIALS).map((namePart) => namePart.charAt(0).toUpperCase()).join("");
+}

package/dist/lib/rich-text/link-markdown-constants.d.ts

@@ -0,0 +1,147 @@
+/**
+ * Shared constants for the rich-text link layer.
+ *
+ * These values back both the read-only renderer (`RichTextContent`) and the
+ * rich link editor (`RichLinkEditor` / `useRichLinkEditor`). They are framework
+ * safe and free of business rules, so they live under `lib` and can be reused by
+ * any feature that needs autolinking plus `[text](url)` markdown support.
+ */
+/** URL protocols accepted when normalizing a markdown link target. */
+export declare const LINK_MARKDOWN_ALLOWED_PROTOCOL: {
+    readonly http: "http:";
+    readonly https: "https:";
+};
+/** Protocol prepended to bare domains that lack an explicit scheme. */
+export declare const LINK_PROTOCOL_PREFIX: {
+    readonly default: "https://";
+};
+/** Tokens used to assemble and recognize `[text](url)` markdown links. */
+export declare const LINK_MARKDOWN_FORMAT: {
+    readonly closeLabel: "]";
+    readonly closeUrl: ")";
+    readonly openLabel: "[";
+    readonly openUrl: "](";
+    readonly suppressedUrl: "#";
+};
+/**
+ * Parentheses that the `[text](url)` markdown URL group cannot represent
+ * unescaped, paired with their percent-encoded equivalents. The URL group only
+ * accepts balanced single-level `(...)` pairs, so any other paren must be
+ * encoded when serializing a link target; browsers decode `%28`/`%29` back to
+ * the literal character when the link is opened.
+ */
+export declare const LINK_MARKDOWN_URL_PAREN: {
+    readonly close: ")";
+    readonly encodedClose: "%29";
+    readonly encodedOpen: "%28";
+    readonly open: "(";
+};
+/** Patterns matching characters that must be escaped inside link label text. */
+export declare const LINK_MARKDOWN_ESCAPE_PATTERN: {
+    readonly backslash: RegExp;
+    readonly closeLabel: RegExp;
+    readonly lineBreak: RegExp;
+    readonly openLabel: RegExp;
+};
+/** Escape sequences paired with `LINK_MARKDOWN_ESCAPE_PATTERN`. */
+export declare const LINK_MARKDOWN_ESCAPE_VALUE: {
+    readonly backslash: "\\";
+    readonly escapedBackslash: "\\\\";
+    readonly escapedCloseLabel: "\\]";
+    readonly escapedLineBreak: "\\n";
+    readonly escapedOpenLabel: "\\[";
+    readonly lineBreakToken: "n";
+};
+/** Discriminant for the parsed rich-text segments (plain text vs. link). */
+export declare const RICH_TEXT_SEGMENT_TYPE: {
+    readonly link: "link";
+    readonly text: "text";
+};
+/** Whether an editor link is explicit (`[text](url)`) or a suppressed autolink. */
+export declare const RICH_LINK_KIND: {
+    readonly explicit: "explicit";
+    readonly suppressed: "suppressed";
+};
+/** Origin of a preview link segment: auto-detected URL vs. explicit link. */
+export declare const RICH_PREVIEW_LINK_SOURCE: {
+    readonly automatic: "automatic";
+    readonly explicit: "explicit";
+};
+/** Editing modes of the link popover. */
+export declare const RICH_LINK_POPOVER_MODE: {
+    readonly actions: "actions";
+    readonly edit: "edit";
+};
+/**
+ * Regular expressions used to detect links in plain text.
+ *
+ * The URL character classes exclude both `)` and `]` so a URL wrapped in
+ * brackets or parentheses (`[https://example.com/path]`) stops at the closing
+ * delimiter instead of swallowing it into the link target. Balanced `(...)`
+ * inside the URL is still matched through the dedicated paren-balancing group.
+ */
+export declare const LINK_PATTERN: {
+    readonly bareDomain: RegExp;
+    readonly containsWhitespace: RegExp;
+    readonly bareUrl: RegExp;
+    readonly hostBoundary: RegExp;
+    readonly markdown: RegExp;
+    readonly protocolPrefix: RegExp;
+    readonly trailingPunctuation: RegExp;
+    readonly whitespace: RegExp;
+};
+/**
+ * Public top-level domains recognized when auto-linking a scheme-less bare
+ * domain found in prose. `new URL()` accepts any syntactically valid hostname,
+ * so without this allowlist Spanish abbreviations like `EE.UU.` or
+ * end-of-sentence transitions like `China.Por` would resolve to bogus hosts and
+ * become clickable links. It covers the common gTLDs plus every assigned
+ * two-letter ccTLD; unknown suffixes such as `uu` or `por` are intentionally
+ * absent. This gates only the automatic detection path: explicit `http(s)://`
+ * URLs and links the user pastes deliberately bypass it and stay permissive.
+ */
+export declare const KNOWN_TOP_LEVEL_DOMAINS: Set<string>;
+/** Capture group indexes of `LINK_PATTERN.markdown`. */
+export declare const LINK_MARKDOWN_MATCH_GROUP: {
+    readonly text: 1;
+    readonly url: 2;
+};
+/** Sentinel returned by the text diff when no change is found. */
+export declare const TEXT_DIFF_FALLBACK_INDEX: {
+    readonly notFound: -1;
+};
+/** Separator used to build a stable key for preview link segments. */
+export declare const PREVIEW_LINK_KEY_SEPARATOR: {
+    readonly value: ":";
+};
+/** Clipboard data type read on paste inside the editor. */
+export declare const RICH_TEXT_CLIPBOARD_DATA_TYPE: {
+    readonly plainText: "text/plain";
+};
+/** `InputEvent.inputType` values handled by the editor's `beforeInput`. */
+export declare const RICH_TEXT_EDITOR_INPUT_TYPE: {
+    readonly deleteContentBackward: "deleteContentBackward";
+    readonly deleteContentForward: "deleteContentForward";
+    readonly insertLineBreak: "insertLineBreak";
+    readonly insertParagraph: "insertParagraph";
+    readonly insertText: "insertText";
+};
+/** Keyboard keys handled by the editor's `keydown`. */
+export declare const RICH_TEXT_EDITOR_KEY: {
+    readonly backspace: "Backspace";
+    readonly delete: "Delete";
+    readonly enter: "Enter";
+};
+/** Direction of a word-wise deletion. */
+export declare const RICH_TEXT_EDITOR_WORD_DIRECTION: {
+    readonly backward: "backward";
+    readonly forward: "forward";
+};
+/** Length of a single editable character. */
+export declare const RICH_TEXT_EDITOR_KEY_LENGTH: {
+    readonly character: 1;
+};
+/** Literal text tokens used by the editor. */
+export declare const RICH_TEXT_EDITOR_TEXT: {
+    readonly lineBreak: "\n";
+};