@businessdash/sdk 0.9.60

package/src/socials.ts

@@ -0,0 +1,230 @@
+/**
+ * Canonical social-profile support.
+ *
+ * The company profile (`storefrontMeta().socials`) is a free-form record keyed
+ * by BIAB's field keys (`meta`, `twitterX`, `tikTok`, …). Consumers kept
+ * re-implementing the key→icon→href mapping by hand and getting BIAB's exact
+ * keys wrong (e.g. mapping `facebook`/`x` and silently dropping `meta`/`twitterX`).
+ * This module is the single source of truth: every platform BIAB supports, in
+ * render order, with a stable icon slug + a handle→URL normalizer, plus alias
+ * resolution so older/lowercase spellings still match.
+ *
+ * `iconSlug` is a https://simpleicons.org slug (render it however you like —
+ * e.g. `https://cdn.simpleicons.org/<slug>`); `null` means there's no brand
+ * glyph, so fall back to a generic icon. For a drop-in React renderer that does
+ * this for you, see `SocialLinks` in `@businessdash/sdk/react`.
+ */
+
+/** A social/profile platform key as stored on the BIAB company profile. */
+export type SocialPlatformKey =
+	| "meta"
+	| "instagram"
+	| "twitterX"
+	| "tikTok"
+	| "youTube"
+	| "linkedIn"
+	| "pinterest"
+	| "threads"
+	| "bluesky"
+	| "mastodon"
+	| "truthSocial"
+	| "googleBusiness"
+	| "yelp"
+	| "nextdoor"
+	| "angi"
+	| "homeAdvisor"
+	| "houzz"
+	| "thumbtack"
+	| "bbb"
+	| "whatsApp"
+	| "discord"
+	| "substack"
+	| "reddit"
+	| "buyMeACoffee"
+	| "kofi"
+	| "patreon"
+	| "twitch"
+	| "vimeo"
+	| "github"
+	| "behance"
+	| "dribbble";
+
+export type SocialPlatformMeta = {
+	key: SocialPlatformKey;
+	/** Human label — use for `aria-label` / `title`. */
+	label: string;
+	/** simple-icons slug, or `null` when there's no brand glyph (use a fallback). */
+	iconSlug: string | null;
+	/** Prefix applied to a bare handle (a value with no scheme). */
+	hrefPrefix?: string;
+};
+
+/** Every platform BIAB supports, in footer render order. */
+export const SOCIAL_PLATFORMS: readonly SocialPlatformMeta[] = [
+	{
+		key: "meta",
+		label: "Facebook",
+		iconSlug: "facebook",
+		hrefPrefix: "https://facebook.com/",
+	},
+	{
+		key: "instagram",
+		label: "Instagram",
+		iconSlug: "instagram",
+		hrefPrefix: "https://instagram.com/",
+	},
+	{ key: "twitterX", label: "X", iconSlug: "x", hrefPrefix: "https://x.com/" },
+	{
+		key: "tikTok",
+		label: "TikTok",
+		iconSlug: "tiktok",
+		hrefPrefix: "https://tiktok.com/@",
+	},
+	{
+		key: "youTube",
+		label: "YouTube",
+		iconSlug: "youtube",
+		hrefPrefix: "https://youtube.com/",
+	},
+	{
+		key: "linkedIn",
+		label: "LinkedIn",
+		iconSlug: "linkedin",
+		hrefPrefix: "https://linkedin.com/",
+	},
+	{
+		key: "pinterest",
+		label: "Pinterest",
+		iconSlug: "pinterest",
+		hrefPrefix: "https://pinterest.com/",
+	},
+	{
+		key: "threads",
+		label: "Threads",
+		iconSlug: "threads",
+		hrefPrefix: "https://threads.net/@",
+	},
+	{ key: "bluesky", label: "Bluesky", iconSlug: "bluesky" },
+	{ key: "mastodon", label: "Mastodon", iconSlug: "mastodon" },
+	{ key: "truthSocial", label: "Truth Social", iconSlug: "truthsocial" },
+	{ key: "googleBusiness", label: "Google", iconSlug: "google" },
+	{ key: "yelp", label: "Yelp", iconSlug: "yelp" },
+	{ key: "nextdoor", label: "Nextdoor", iconSlug: "nextdoor" },
+	{ key: "angi", label: "Angi", iconSlug: null },
+	{ key: "homeAdvisor", label: "HomeAdvisor", iconSlug: null },
+	{ key: "houzz", label: "Houzz", iconSlug: "houzz" },
+	{ key: "thumbtack", label: "Thumbtack", iconSlug: "thumbtack" },
+	{ key: "bbb", label: "Better Business Bureau", iconSlug: null },
+	{
+		key: "whatsApp",
+		label: "WhatsApp",
+		iconSlug: "whatsapp",
+		hrefPrefix: "https://wa.me/",
+	},
+	{ key: "discord", label: "Discord", iconSlug: "discord" },
+	{ key: "substack", label: "Substack", iconSlug: "substack" },
+	{ key: "reddit", label: "Reddit", iconSlug: "reddit" },
+	{ key: "buyMeACoffee", label: "Buy Me a Coffee", iconSlug: "buymeacoffee" },
+	{ key: "kofi", label: "Ko-fi", iconSlug: "kofi" },
+	{ key: "patreon", label: "Patreon", iconSlug: "patreon" },
+	{ key: "twitch", label: "Twitch", iconSlug: "twitch" },
+	{ key: "vimeo", label: "Vimeo", iconSlug: "vimeo" },
+	{
+		key: "github",
+		label: "GitHub",
+		iconSlug: "github",
+		hrefPrefix: "https://github.com/",
+	},
+	{ key: "behance", label: "Behance", iconSlug: "behance" },
+	{ key: "dribbble", label: "Dribbble", iconSlug: "dribbble" },
+];
+
+const PLATFORM_BY_KEY = new Map<string, SocialPlatformMeta>(
+	SOCIAL_PLATFORMS.map((p) => [p.key.toLowerCase(), p]),
+);
+
+/** Older / alternate spellings → canonical key (all compared lowercased + de-punctuated). */
+const ALIASES: Record<string, SocialPlatformKey> = {
+	facebook: "meta",
+	fb: "meta",
+	x: "twitterX",
+	twitter: "twitterX",
+	tiktok: "tikTok",
+	youtube: "youTube",
+	linkedin: "linkedIn",
+	google: "googleBusiness",
+	googlemybusiness: "googleBusiness",
+	truthsocial: "truthSocial",
+	homeadvisor: "homeAdvisor",
+	betterbusinessbureau: "bbb",
+	whatsapp: "whatsApp",
+	buymeacoffee: "buyMeACoffee",
+	"ko-fi": "kofi",
+};
+
+/** Strip case + separators so `Truth Social`, `truth_social`, `truthSocial` all collapse. */
+function canonicalize(raw: string): string {
+	return raw.toLowerCase().replace(/[\s_-]+/g, "");
+}
+
+/** Resolve any incoming social key (BIAB key, alias, or loose spelling) to its platform meta. */
+export function resolveSocialPlatform(key: string): SocialPlatformMeta | null {
+	const c = canonicalize(key);
+	const direct = PLATFORM_BY_KEY.get(c);
+	if (direct) return direct;
+	const aliased = ALIASES[c];
+	return aliased ? (PLATFORM_BY_KEY.get(aliased.toLowerCase()) ?? null) : null;
+}
+
+/** Turn a stored value (full URL or bare handle) into an href using the platform prefix. */
+export function socialHref(
+	value: string,
+	platform: SocialPlatformMeta,
+): string {
+	const v = value.trim();
+	if (/^(https?:\/\/|mailto:|tel:)/i.test(v)) return v;
+	if (platform.hrefPrefix) return platform.hrefPrefix + v.replace(/^@/, "");
+	return `https://${v.replace(/^\/+/, "")}`;
+}
+
+export type ResolvedSocialProfile = {
+	key: SocialPlatformKey;
+	label: string;
+	iconSlug: string | null;
+	url: string;
+};
+
+/**
+ * Turn the company profile's `socials` record into a render-ready, de-duped list
+ * in canonical order — every platform that has a non-empty value, resolved to its
+ * label, icon slug, and a normalized URL. Empty values and unknown keys are
+ * dropped. Pass `storefrontMeta().socials` straight in.
+ */
+export function resolveSocialProfiles(
+	socials: unknown,
+): ResolvedSocialProfile[] {
+	if (!socials || typeof socials !== "object") return [];
+	const present = new Map<SocialPlatformKey, string>();
+	for (const [rawKey, rawVal] of Object.entries(
+		socials as Record<string, unknown>,
+	)) {
+		if (typeof rawVal !== "string") continue;
+		const value = rawVal.trim();
+		if (!value) continue;
+		const platform = resolveSocialPlatform(rawKey);
+		if (!platform || present.has(platform.key)) continue;
+		present.set(platform.key, value);
+	}
+	const rows: ResolvedSocialProfile[] = [];
+	for (const platform of SOCIAL_PLATFORMS) {
+		const value = present.get(platform.key);
+		if (!value) continue;
+		rows.push({
+			key: platform.key,
+			label: platform.label,
+			iconSlug: platform.iconSlug,
+			url: socialHref(value, platform),
+		});
+	}
+	return rows;
+}