jekyll-theme-resume 1.3.0

data/_includes/dark-mode-toggle.html

@@ -0,0 +1,202 @@
+{%- comment -%}
+  Component: Dark Mode Toggle Widget
+  - Purpose: Provides an accessible, persistent floating toggle button for switching between Light and Dark color themes.
+  - Activation Cascade:
+    1. Evaluates the site-level switch: `site.dark_mode` (boolean or "enabled").
+    2. Applies page-level override if specified in front matter (`page.dark_mode: true/false/enabled`).
+    3. Renders button markup and client controller only when enabled.
+  - Localization: aria-label/title come from the current page's locale.ui.dark_mode_toggle.
+  - Visual Design: Floating circular action button fixed in the viewport.
+  - Print Media: Decorated with `class="no-print"` to ensure it is excluded from printed resumes or PDF generation.
+  - CSS Integration: Operates with CSS custom properties defined in `_sass/_dark-mode.scss`.
+{%- endcomment -%}
+
+{%- assign lang = page.lang | default: site.default_lang | default: 'en' -%}
+{%- assign locale = site.data.locales[lang] | default: site.data.locales[site.default_lang] -%}
+{% assign dark_mode_enabled = false %}
+{% if site.dark_mode == "enabled" or site.dark_mode == true %}
+  {% assign dark_mode_enabled = true %}
+{% endif %}
+{% if page.dark_mode == false %}
+  {% assign dark_mode_enabled = false %}
+{% elsif page.dark_mode == true or page.dark_mode == "enabled" %}
+  {% assign dark_mode_enabled = true %}
+{% endif %}
+
+{% if dark_mode_enabled %}
+<!-- Dark Mode Toggle Button (Two-state: System Default vs Pinned Override) -->
+<button
+  id="dark-mode-toggle"
+  class="dark-mode-toggle no-print"
+  type="button"
+  aria-label="{{ locale.ui.dark_mode_toggle }}"
+  title="{{ locale.ui.dark_mode_toggle }}"
+  aria-pressed="false"
+  data-pinned="false"
+>
+  {%- comment -%}
+    Inline SVG Icons:
+    - Both icons have `aria-hidden="true"` and `focusable="false"` to prevent assistive technologies
+      from announcing raw vector graphics and to keep keyboard focus solely on the parent <button>.
+    - Visibility is toggled via CSS selectors based on `data-theme` or system color-scheme preference.
+  {%- endcomment -%}
+  <!-- Sun Icon: Visible in dark mode / indicates switching to light mode -->
+  <svg
+    class="dark-mode-icon dark-mode-icon-sun"
+    xmlns="http://www.w3.org/2000/svg"
+    width="20"
+    height="20"
+    viewBox="0 0 24 24"
+    fill="none"
+    stroke="currentColor"
+    stroke-width="2"
+    stroke-linecap="round"
+    stroke-linejoin="round"
+    aria-hidden="true"
+    focusable="false"
+  >
+    <circle cx="12" cy="12" r="5"></circle>
+    <line x1="12" y1="1" x2="12" y2="3"></line>
+    <line x1="12" y1="21" x2="12" y2="23"></line>
+    <line x1="4.22" y1="4.22" x2="5.64" y2="5.64"></line>
+    <line x1="18.36" y1="18.36" x2="19.78" y2="19.78"></line>
+    <line x1="1" y1="12" x2="3" y2="12"></line>
+    <line x1="21" y1="12" x2="23" y2="12"></line>
+    <line x1="4.22" y1="19.78" x2="5.64" y2="18.36"></line>
+    <line x1="18.36" y1="5.64" x2="19.78" y2="4.22"></line>
+  </svg>
+
+  <!-- Moon Icon: Visible in light mode / indicates switching to dark mode -->
+  <svg
+    class="dark-mode-icon dark-mode-icon-moon"
+    xmlns="http://www.w3.org/2000/svg"
+    width="20"
+    height="20"
+    viewBox="0 0 24 24"
+    fill="none"
+    stroke="currentColor"
+    stroke-width="2"
+    stroke-linecap="round"
+    stroke-linejoin="round"
+    aria-hidden="true"
+    focusable="false"
+  >
+    <path d="M21 12.79A9 9 0 1 1 11.21 3 7 7 0 0 0 21 12.79z"></path>
+  </svg>
+</button>
+
+<script>
+  /**
+   * Dark Mode Client Controller
+   * Encapsulated in an IIFE to prevent polluting the global window namespace.
+   *
+   * Two-State Logic Architecture:
+   * 1. Unpinned (System Default): Follows the OS `prefers-color-scheme`. `localStorage` contains no value.
+   *    Listens dynamically to OS dark/light mode switches.
+   * 2. Pinned (User Override): Explicit user choice saved in `localStorage.setItem('color-scheme', ...)`.
+   *    Clicking the button when pinned resets the theme back to the system default (clearing localStorage).
+   */
+  (function () {
+    var toggleBtn = document.getElementById('dark-mode-toggle');
+    if (!toggleBtn) return;
+
+    var metaTheme = document.querySelector('meta[name="color-scheme"]');
+
+    // Detects user's operating system level theme preference
+    function getSystemTheme() {
+      if (window.matchMedia) {
+        return window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light';
+      }
+      return 'light';
+    }
+
+    // Storage Error Boundary: Accesses localStorage inside try/catch to safely handle
+    // private browsing modes (e.g. Safari Private Browsing) or restricted cookie security settings.
+    function getSavedTheme() {
+      try {
+        var val = localStorage.getItem('color-scheme');
+        if (val === 'dark' || val === 'light') {
+          return val;
+        }
+        return null;
+      } catch (e) {
+        return null;
+      }
+    }
+
+    // Synchronizes data attributes on <html> and <meta name="color-scheme">
+    function syncState() {
+      var saved = getSavedTheme();
+      if (saved !== null) {
+        document.documentElement.setAttribute('data-color-scheme', saved);
+        document.documentElement.setAttribute('data-theme', saved);
+        if (metaTheme) {
+          metaTheme.setAttribute('content', saved);
+        }
+      } else {
+        document.documentElement.removeAttribute('data-color-scheme');
+        document.documentElement.removeAttribute('data-theme');
+        if (metaTheme) {
+          metaTheme.setAttribute('content', 'light dark');
+        }
+      }
+    }
+
+    // Updates ARIA accessibility attributes and data-pinned status.
+    // aria-label/title are set once from locale.ui.dark_mode_toggle in the
+    // server-rendered markup and are not re-localized client-side.
+    function updateUI() {
+      var saved = getSavedTheme();
+      var isPinned = (saved !== null);
+      var effectiveTheme = isPinned ? saved : getSystemTheme();
+
+      toggleBtn.setAttribute('data-pinned', isPinned ? 'true' : 'false');
+      toggleBtn.setAttribute('aria-pressed', isPinned ? 'true' : 'false');
+      toggleBtn.setAttribute('data-current-theme', effectiveTheme);
+    }
+
+    // Toggles theme state: cycles between user-pinned override and system default
+    function toggleTheme() {
+      var saved = getSavedTheme();
+      if (saved !== null) {
+        // Currently pinned -> reset to system default
+        try {
+          localStorage.removeItem('color-scheme');
+        } catch (e) {}
+        syncState();
+      } else {
+        // Currently unpinned -> pin opposite of current system setting
+        var systemTheme = getSystemTheme();
+        var targetTheme = (systemTheme === 'dark') ? 'light' : 'dark';
+        try {
+          localStorage.setItem('color-scheme', targetTheme);
+        } catch (e) {}
+        syncState();
+      }
+      updateUI();
+    }
+
+    toggleBtn.addEventListener('click', toggleTheme);
+
+    // Reactive System Theme Listener: Adapts UI in real-time when OS theme changes (if unpinned)
+    if (window.matchMedia) {
+      var darkQuery = window.matchMedia('(prefers-color-scheme: dark)');
+      var mqListener = function () {
+        if (!getSavedTheme()) {
+          updateUI();
+        }
+      };
+      if (darkQuery.addEventListener) {
+        darkQuery.addEventListener('change', mqListener);
+      } else if (darkQuery.addListener) {
+        darkQuery.addListener(mqListener);
+      }
+    }
+
+    // Initial hydration on page load
+    syncState();
+    updateUI();
+  })();
+</script>
+{% endif %}
+

data/_includes/data-loader.html

@@ -0,0 +1,42 @@
+{%- comment -%}
+================================================================================
+DYNAMIC DATA LOADER HELPER (_includes/data-loader.html)
+================================================================================
+PURPOSE:
+  Dynamically resolves the root data object (`resume_data`) for the current layout
+  by traversing nested YAML folders in `_data/` based on a dot-separated path.
+
+HOW IT WORKS:
+  1. Default Assignment:
+     Starts with top-level `site.data`. If no custom subpath is configured,
+     the template reads directly from root YAML files (e.g. `_data/experience.yml`).
+
+  2. Subpath Splitting (`split: '.'`):
+     Breaks dot-separated strings into array segments.
+     Example: "2025-06.20250621-PM" -> ["2025-06", "20250621-PM"]
+     Example: "en" -> ["en"]
+
+  3. Recursive Bracket Notation (`resume_data[part]`):
+     Liquid dot notation (site.data.2025-06) breaks on numbers and hyphens.
+     Bracket notation safely accesses arbitrary string keys at any nesting depth:
+     - Level 1: site.data["2025-06"]
+     - Level 2: site.data["2025-06"]["20250621-PM"]
+
+PARAMETERS:
+  - `path` (String, Optional): The dot-path string to resolve (e.g. "en", "ar", "2025-06.v1").
+    Defaults to `site.languages[lang].data_path` (current page.lang, or site.default_lang) if omitted.
+
+OUTPUT:
+  - Sets the global template variable `resume_data` in the calling layout context.
+================================================================================
+{%- endcomment -%}
+{%- assign default_lang_cfg = site.languages[page.lang | default: site.default_lang | default: 'en'] -%}
+{%- assign data_path = include.path | default: default_lang_cfg.data_path -%}
+{%- assign resume_data = site.data -%}
+
+{%- if data_path.size > 0 -%}
+  {%- assign path_parts = data_path | split: '.' -%}
+  {%- for part in path_parts -%}
+    {%- assign resume_data = resume_data[part] -%}
+  {%- endfor -%}
+{%- endif -%}

data/_includes/date-formatter.html

@@ -0,0 +1,63 @@
+{%- comment -%}
+  Universal Date Formatter
+  Formats a single date for any locale from _data/locales/<lang>.yml. Single canonical date
+  formatting hook for every language, designed to cleanly host future calendar-system
+  extensions (e.g. Feature 2.9 Dual Gregorian / Hijri Localization) without reintroducing
+  language-isolated includes such as the legacy _includes/ar-date.html.
+
+  Usage:
+    {% include date-formatter.html date=role.startdate %}
+    {% include date-formatter.html date=role.startdate style="MDY" %}
+    {% include date-formatter.html date=role.startdate lang="ar" %}
+
+  Parameters:
+    - date: the date to format, or a present-tense marker string (e.g. "Present"). Required.
+    - style: "MDY" for "Month Day, Year"; anything else (default "MY") for "Month Year".
+    - lang: locale code to format in. Defaults to the active page/site language.
+{%- endcomment -%}
+{%- assign lang = include.lang | default: page.lang | default: site.default_lang | default: 'en' -%}
+{%- assign locale = site.data.locales[lang] | default: site.data.locales[site.default_lang] -%}
+{%- assign style = include.style | default: "MY" -%}
+
+{%- if include.date and include.date != "" -%}
+  {%- comment -%} Case-insensitive match against locale.present_values (e.g. "Present", "حتى الآن") {%- endcomment -%}
+  {%- assign date_downcase = include.date | downcase -%}
+  {%- assign is_present = false -%}
+  {%- for present_value in locale.present_values -%}
+    {%- assign present_value_downcase = present_value | downcase -%}
+    {%- if present_value_downcase == date_downcase -%}
+      {%- assign is_present = true -%}
+    {%- endif -%}
+  {%- endfor -%}
+
+  {%- if is_present -%}
+    {{ locale.ui.present }}
+  {%- else -%}
+    {%- comment -%}
+      Split the ISO string ourselves: Liquid's `date` filter reads a bare year (2018) as a
+      Unix timestamp and cannot parse YYYY-MM. YAML Date objects stringify to YYYY-MM-DD.
+      Anything that is not YYYY, YYYY-MM or YYYY-MM-DD is printed verbatim.
+    {%- endcomment -%}
+    {%- assign date_parts = include.date | append: "" | slice: 0, 10 | split: "-" -%}
+    {%- assign year = date_parts[0] -%}
+    {%- assign year_check = year | plus: 0 | append: "" -%}
+    {%- assign month_num = date_parts[1] | plus: 0 -%}
+    {%- assign day = date_parts[2] | plus: 0 -%}
+    {%- assign month_name = nil -%}
+    {%- if date_parts[1].size == 2 and month_num >= 1 and month_num <= 12 -%}
+      {%- assign month_index = month_num | minus: 1 -%}
+      {%- assign month_name = locale.months[month_index] -%}
+    {%- endif -%}
+    {%- if year.size != 4 or year_check != year or date_parts.size > 3 -%}
+      {{ include.date }}
+    {%- elsif date_parts.size == 1 -%}
+      {{ year }}
+    {%- elsif month_name == nil -%}
+      {{ include.date }}
+    {%- elsif style == "MDY" and date_parts.size == 3 and day > 0 -%}
+      {{ month_name }} {{ day }}, {{ year }}
+    {%- else -%}
+      {{ month_name }} {{ year }}
+    {%- endif -%}
+  {%- endif -%}
+{%- endif -%}

data/_includes/grouped-item-list.html

@@ -0,0 +1,53 @@
+{%- comment -%}
+Shared renderer for the Experience and Volunteering sections: groups entries by
+company, sorts each group's roles newest-first, and formats each role's duration
+or date range. Extracted so a fix to one section's logic always applies to both.
+
+Params:
+  items - the section's data array (e.g. resume_data.experience)
+  lang  - the current language code
+{%- endcomment -%}
+{%- assign active_entries = include.items | where: "active", true -%}
+{%- assign groups = active_entries | group_by: "company" -%}
+
+{%- for group in groups -%}
+    <div class="resume-item" itemscope itemprop="worksFor" itemtype="http://schema.org/Organization">
+        <h3 class="resume-item-title" itemprop="name">{{ group.name }}</h3>
+
+        {%- assign roles = group.items | sort: "startdate" | reverse -%}
+        {%- for role in roles -%}
+            {%- assign has_dates = false -%}
+            {%- if role.durations or role.startdate -%}
+                {%- assign has_dates = true -%}
+            {%- endif -%}
+
+            {%- if role.position.size > 0 or has_dates or role.location.size > 0 -%}
+                <h4 class="resume-item-details" itemprop="description">
+                    {%- if role.position.size > 0 -%}
+                        {{ role.position }}
+                    {%- endif -%}
+
+                    {%- if has_dates -%}
+                        {% if role.position.size > 0 %} &bull; {% endif %}
+                        {% if role.durations %}
+                            {% for time in role.durations %}{{ time.duration }} {% endfor %}
+                        {% else %}
+                            {%- assign role_enddate = role.enddate | default: "Present" -%}
+                            {% include date-formatter.html date=role.startdate lang=include.lang style="MY" %} &ndash;
+                            {% include date-formatter.html date=role_enddate lang=include.lang style="MY" %}
+                        {% endif %}
+                    {%- endif -%}
+
+                    {%- if role.location.size > 0 -%}
+                        {% if role.position.size > 0 or has_dates %} &bull; {% endif %}
+                        {{ role.location }}
+                    {%- endif -%}
+                </h4>
+            {%- endif -%}
+
+            {%- if site.enable_summary == true and role.summary -%}
+                <div class="resume-item-copy">{{ role.summary }}</div>
+            {%- endif -%}
+        {%- endfor -%}
+    </div><!-- end of grouped resume-item -->
+{%- endfor -%}

data/_includes/hreflang.html

@@ -0,0 +1,58 @@
+{% comment %}
+==================================================================
+START: HREFLANG TAGS FOR MULTILINGUAL SEO
+This logic generates the <link rel="alternate"> tags that tell
+search engines about the different language versions of this page.
+It only runs if a 't_id' (Translation ID) is set in the page's front matter.
+
+WHY THIS MATTERS:
+Search engines (Google, Bing, Yandex) require bidirectional hreflang links across
+all localized versions of equivalent content to prevent duplicate content penalties
+and to direct international visitors to the correct regional/language variant.
+
+HOW IT WORKS:
+- Pages representing the same document in different languages (e.g. English and Arabic CVs)
+  share an identical `t_id` identifier in front matter.
+- site.pages is queried to locate all translation peers.
+- Absolute URLs are required by RFC 8288 and Google Search Console standards.
+- The 'x-default' fallback is explicitly mapped to the English edition for unmatched locales.
+==================================================================
+{% endcomment %}
+{% if page.t_id %}
+
+  {% comment %}
+    1. Find all pages on the site that share the *same* 't_id' as this
+       current page. Store them in a new list called 'translations'.
+  {% endcomment %}
+  {% assign translations = site.pages | where: "t_id", page.t_id %}
+
+  {% comment %}
+    2. Loop through every page found in the 'translations' list.
+       't' represents each individual page in the loop.
+  {% endcomment %}
+  {% for t in translations %}
+    {% comment %}
+      Print an 'alternate' tag for each page, using its
+      'lang' (e.g., "en", "ar") and its full 'url'.
+    {% endcomment %}
+    <link rel="alternate" hreflang="{{ t.lang | escape }}" href="{{ t.url | absolute_url }}" />
+  {% endfor %}
+
+  {% comment %}
+    3. Find the site's default-language page from the 'translations' list
+       to use as the "default" version.
+  {% endcomment %}
+  {% assign default_lang = site.default_lang | default: "en" %}
+  {% assign default_page = translations | where: "lang", default_lang | first %}
+  
+  {% comment %}
+    4. If an English version was found, print the 'x-default' tag.
+       This tells Google which page to show if the user's
+       language doesn't match any of our versions.
+  {% endcomment %}
+  {% if default_page %}
+    <link rel="alternate" hreflang="x-default" href="{{ default_page.url | absolute_url }}" />
+  {% endif %}
+
+{% endif %}
+{% comment %} ================= End HREFLANG logic ================= {% endcomment %}

data/_includes/language-switcher.html

@@ -0,0 +1,72 @@
+{%- comment -%}
+Include: Reusable Multilingual Language Switcher Component (Feature 1.2; dropdown redesign Feature 2.12)
+- Purpose: Floating dropdown listing links to every other configured language's resume.
+- Positioning: Fixed top-left viewport corner (see _sass/_layout.scss).
+- Markup: Native <details>/<summary> disclosure — zero JavaScript, full keyboard support
+  (Enter/Space toggles the panel open and closed; browsers do not natively close it on Esc
+  or outside click, matching plain <details> behavior everywhere else). Scales to any number
+  of configured languages without growing a row of buttons.
+- Link Resolution (two-tier), per target language:
+    1. Discovers the counterpart page via page.t_id + lang match (site.pages).
+    2. Falls back to languages.<lang>.url from _config.yml.
+- Accessibility: The trigger's visible text is the current locale's ui.language_switcher
+  string. The panel is a <nav> landmark labelled with the same string. Each link is labelled
+  with its own locale's ui.language_name.
+- Print Safety: Decorated with class="no-print" — hidden on printed resume sheets.
+- Toggle: Disabled via site.resume_language_switcher: false in _config.yml.
+{%- endcomment -%}
+
+{% if site.resume_language_switcher != false and page.language_switcher != false %}
+  {%- assign current_lang = page.lang | default: site.default_lang | default: 'en' -%}
+  {%- assign current_locale = site.data.locales[current_lang] | default: site.data.locales[site.default_lang] -%}
+
+  <details class="language-switcher no-print">
+    <summary class="language-switcher-trigger">
+      <span class="lang-icon" aria-hidden="true">🌐</span>
+      <span class="language-switcher-label">{{ current_locale.ui.language_switcher }}</span>
+    </summary>
+    <nav class="language-switcher-panel" aria-label="{{ current_locale.ui.language_switcher }}">
+      {%- comment -%}
+      IMPORTANT: {% include %} shares Liquid variable scope with its caller (resume.html),
+      so every variable assigned in this loop body must use a switch_-prefixed name that
+      cannot collide with resume.html's own lang/locale/lang_cfg - otherwise the last loop
+      iteration's values would silently leak out and corrupt the rest of the caller's render.
+      {%- endcomment -%}
+      {% for switch_entry in site.languages %}
+        {%- assign switch_lang = switch_entry[0] -%}
+        {%- assign switch_lang_cfg = switch_entry[1] -%}
+        {%- if switch_lang != current_lang -%}
+          {%- assign switch_locale = site.data.locales[switch_lang] -%}
+
+          {%- comment -%}
+          TIER 1: Auto-discover counterpart page by matching page.t_id + target language.
+          Both pages must have the same t_id value in their front matter (e.g., t_id: cv-main).
+          {%- endcomment -%}
+          {%- assign switch_url = nil -%}
+          {%- if page.t_id -%}
+            {%- assign switch_matched_page = site.pages | where: "t_id", page.t_id | where: "lang", switch_lang | first -%}
+            {%- if switch_matched_page -%}
+              {%- assign switch_url = switch_matched_page.url | relative_url -%}
+            {%- endif -%}
+          {%- endif -%}
+
+          {%- comment -%}
+          TIER 2: Fall back to languages.<lang>.url from _config.yml.
+          {%- endcomment -%}
+          {%- unless switch_url -%}
+            {%- assign switch_url = switch_lang_cfg.url | relative_url -%}
+          {%- endunless -%}
+
+          <a href="{{ switch_url }}"
+             class="lang-switch-btn"
+             aria-label="{{ switch_locale.ui.language_name }}"
+             title="{{ switch_locale.ui.language_name }}"
+             dir="{{ switch_locale.direction }}">
+            <span class="lang-icon" aria-hidden="true">🌐</span>
+            <span class="lang-label-target">{{ switch_locale.ui.language_name }}</span>
+          </a>
+        {%- endif -%}
+      {% endfor %}
+    </nav>
+  </details>
+{% endif %}

data/_includes/print-social-links.html

@@ -0,0 +1,23 @@
+{%- comment -%}
+  Component: Print-Only Social & Contact Links
+  - Purpose: Renders full plaintext URLs for physical paper printouts and PDF exports
+    where clickable icon-only links cannot be followed.
+  - Localization: Platform labels come from locale.ui.social_labels.
+  - Bidi Protection: Every URL is wrapped in `<span dir="ltr">` to ensure web addresses,
+    slashes, and domain names are never reversed or scrambled in an RTL reading context.
+{%- endcomment -%}
+<!-- and guess where these are defined? Yup, you guessed it: the _config.yml file -->
+{% if site.resume_print_social_links %}
+{%- assign lang = page.lang | default: site.default_lang | default: 'en' -%}
+{%- assign locale = site.data.locales[lang] | default: site.data.locales[site.default_lang] -%}
+<ul>
+
+    {% for network in site.data.social_networks %}
+      {% assign value = site.social_links[network.key] %}
+      {% if value %}
+        <li><strong>{{ locale.ui.social_labels[network.key] }}</strong>: <span dir="ltr">{{ value | escape }}</span></li>
+      {% endif %}
+    {% endfor %}
+
+</ul>
+{% endif %}