add: front (9) хлебные крошки

lpon_site/frontend/views.py

@@ -1,13 +1,108 @@
 #
 
+from dataclasses import dataclass
+
 from django.shortcuts import render
 from django.http import HttpRequest, HttpResponse
 
 # Create your views here.
 
+
+@dataclass(frozen=True)
+class BreadcrumbItem:
+    """
+    Один пункт хлебных крошек (например, "Главная", "Каталог", "Винил").
+
+    ЧТО ТАКОЕ dataclass (если видите это в первый раз)
+    ----------------------------------------------------
+    `@dataclass` — это декоратор из стандартной библиотеки Python (модуль `dataclasses`).
+    Он берёт класс, в котором просто перечислены имена полей и их типы (без ручного
+    __init__), и САМ генерирует за вас служебные методы:
+        - __init__(self, title, url=None)  — конструктор класса. Благодаря нему можно
+          писать BreadcrumbItem(title="Каталог", url="/catalog") без единой строчки
+          кода конструктора;
+        - __repr__   — красивое текстовое представление для print()/логов, например:
+          BreadcrumbItem(title='Каталог', url='/catalog');
+        - __eq__     — сравнение двух объектов по значениям полей, то есть
+          BreadcrumbItem('Каталог', '/catalog') == BreadcrumbItem('Каталог', '/catalog')
+          вернёт True (без dataclass пришлось бы сравнивать id() объектов).
+
+    Без dataclass пришлось бы писать руками:
+
+        class BreadcrumbItem:
+            def __init__(self, title, url=None):
+                self.title = title
+                self.url = url
+
+    С dataclass — просто пишем поля (см. ниже) и всё перечисленное выше Python
+    сгенерирует сам. Это НЕ меняет то, как объект используется — просто экономит
+    код и снижает риск ошибок при ручном написании __init__/__repr__/__eq__.
+
+    Чем dataclass отличается от NamedTuple (typing.NamedTuple)?
+    ---------------------------------------------------------------
+    Обе конструкции решают одну и ту же задачу — описать "структуру из нескольких
+    полей" без лишнего кода, но по-разному устроены внутри:
+        - `NamedTuple` — это, по сути, обычный tuple с именами полей. Он ВСЕГДА
+          неизменяем (immutable), поддерживает распаковку как обычный tuple
+          (title, url = item) и итерацию (for value in item);
+        - `dataclass` — это обычный класс. По умолчанию он изменяем (можно
+          присвоить item.title = "..." в любой момент), но можно сделать
+          неизменяемым через параметр frozen=True (как сделано ниже). В отличие
+          от NamedTuple, dataclass НЕ поддерживает распаковку как tuple, зато его
+          проще расширять методами, наследованием и сложными полями по умолчанию
+          (списками, словарями и т.п.).
+
+    Для хлебных крошек подошёл бы любой из двух вариантов. Здесь выбран dataclass
+    с frozen=True — то есть объект ведёт себя как неизменяемый: попытка сделать
+    `item.title = "другое значение"` после создания вызовет исключение. Это
+    логично: один и тот же пункт крошек не должен "мутировать" по ходу рендеринга
+    страницы.
+
+    КОНТРАКТ С ШАБЛОНОМ (важно!):
+    -------------------------------
+    Шаблон lpon_site/templates/block/breadcrumbs.html ожидает контекстную
+    переменную `breadcrumbs` — список объектов именно с такими двумя полями:
+
+    Атрибуты:
+        title (str):
+            Видимый текст пункта, например "Каталог", "Винил".
+        url (str | None):
+            Ссылка на пункт. Если None (значение по умолчанию) — пункт
+            считается ТЕКУЩЕЙ страницей: шаблон покажет его БЕЗ ссылки, с
+            атрибутом aria-current="page". Обычно url=None указывают только
+            у ПОСЛЕДНЕГО пункта в списке крошек.
+
+    ВАЖНО: пункт "Главная" в этот список включать НЕ нужно — ссылку на
+    главную страницу (в виде иконки домика) шаблон breadcrumbs.html
+    добавляет сам, одинаково для всех страниц. Список крошек должен
+    начинаться сразу со следующего уровня (например, с "Каталог").
+
+    Пример использования — см. функцию catalog() ниже.
+    """
+    title: str
+    url: str | None = None
+
+
 def index(request: HttpRequest | None) -> HttpResponse:
     return render(request, 'index.html', {})
 
 
 def catalog(request: HttpRequest | None) -> HttpResponse:
-    return render(request, 'catalog.html', {})
+    """
+    Страница каталога (пока черновик вёрстки, см. lpon_site/templates/catalog.html).
+
+    ТЕСТОВЫЕ ДАННЫЕ ДЛЯ ХЛЕБНЫХ КРОШЕК:
+    В реальной вьюхе список крошек будет собираться динамически (в зависимости
+    от применённых фильтров, выбранной категории и т.п.). Пока каталог — черновик,
+    здесь захардкожен простой пример из двух пунктов, чтобы продемонстрировать
+    работу block/breadcrumbs.html: "Каталог" — обычный пункт со ссылкой, а
+    "Компакт-кассеты" — текущая страница (url не передан, поэтому он покажется без
+    ссылки). Пункт "Главная" передавать не нужно — его в виде иконки домика
+    сам добавляет шаблон breadcrumbs.html.
+    """
+    breadcrumbs = [
+        BreadcrumbItem(title="Каталог", url="/catalog"),
+        BreadcrumbItem(title="Компакт-кассеты", url="/catalog/compact-cassettes"),  # url передан -> обычный пункт со ссылкой
+        BreadcrumbItem(title="Для перезаписи" ),  # url передан -> обычный пункт со ссылкой
+    ]
+    return render(request, 'catalog.html', {"breadcrumbs": breadcrumbs})

lpon_site/templates/block/breadcrumbs.html

@@ -0,0 +1,77 @@
+{% load static %}{% comment %}
+  Шаблон "Хлебные крошки" (breadcrumbs).
+
+  ЗАЧЕМ ЭТОТ БЛОК:
+    Показывает пользователю путь от главной страницы до текущей
+    ("Главная > Каталог > Винил > The Beatles > Abbey Road"),
+    помогая ориентироваться в структуре сайта + SEO
+
+    Первый пункт (ссылка "Главная") — вставляется САМИМ этим шаблоном,
+    без участия контекста. Она одинакова абсолютно на всех страницах
+    сайта, поэтому передавать её через каждую вьюху не нужно: переменная
+    `breadcrumbs`, которую передаёт вызывающая вьюха, НЕ должна содержать
+    пункт "Главная" — начинайте сразу со следующего уровня (например,
+    "Каталог"), см. КОНТРАКТ ниже.
+
+    Вместо слова "Главная" используется готовая иконка домика из статики
+    проекта — public/static/svgs/ico-home.svg, подключаемая через <img />,
+    БЕЗ подключения иконочного шрифта (Font Awesome, IcoMoon и т.п.).
+    Пока иконок в проекте немного, тянуть ради них целый шрифт (лишние
+    килограммы + лишний HTTP-запрос + зависимость от CDN) — невыгодно;
+    один SVG-файл дешевле и не требует внешних подключений.
+
+    ВАЖНО про цвет иконки: иконка из img-тега НЕ наследует
+    цвет текста и не меняется на hover — она остаётся такой, какая
+    нарисована в самом файле (чёрная заливка). Чтобы иконка оставалась
+    видимой на тёмном фоне в тёмной теме, применён CSS-фильтр dark:invert
+    (инвертирует чёрный в белый только в тёмной теме, в светлой теме
+    фильтр не применяется).
+
+  КОНТРАКТ (что именно должна передать вызывающая вьюха/шаблон):
+    Контекстная переменная `breadcrumbs` — список (или любой другой iterable)
+    объектов с двумя атрибутами (БЕЗ пункта "Главная" — его добавляет сам
+    шаблон, см. выше):
+      - title: str        — видимый текст пункта ("Каталог", "Винил"...);
+      - url:   str | None — ссылка на пункт.
+                            Если url = None (или отсутствует/пуст) — пункт
+                            считается ТЕКУЩЕЙ страницей и рендерится БЕЗ ссылки,
+                            с атрибутом aria-current="page".
+                            Обычно url=None указывают только у ПОСЛЕДНЕГО пункта.
+
+    В проекте для этого используется dataclass `BreadcrumbItem` — см. подробное
+    объяснение (с комментариями "для новичков") прямо в docstring класса в файле
+    lpon_site/frontend/views.py. Шаблону не важно, dataclass это, NamedTuple или
+    просто объект с нужными атрибутами — главное, чтобы у каждого элемента были
+    поля `title` и `url`.
+
+{% endcomment %}{% if breadcrumbs %}<nav aria-label="Хлебные крошки" class="px-4 py-2 text-sm text-slate-500 dark:text-slate-100 hidden md:block bg-slate-50 dark:bg-slate-900 m-2">
+  {# aria-label="Хлебные крошки" — для доступности, чтобы скринридеры озвучивали #}
+  {# пользователю, что это именно хлебные крошки, а не просто список ссылок. #}
+  {# hidden md:block — скрываем на маленьких экранах (мобильных) #}
+  <ol class="flex flex-wrap items-center gap-x-2">{% comment %}
+  	    ol вместо ul — потому что это упорядоченный список, а не просто
+        набор ссылок. Важный момент для доступности и SEO.{% endcomment %}
+    <li class="flex items-center gap-x-2">{# Ссылка на главную (домик) #}
+      {# пунктирное подчёркивание и цвет теперь задаются типовым стилем #}
+      {# ссылок (см. css/tailwind-custom.css, @layer base { a {...} }); #}
+      {# opacity-70/hover/transition — собственный эффект именно для иконки-домика. #}
+      <a href="/" aria-label="Главная" class="opacity-70 hover:opacity-100 transition-opacity py-0.5">
+        <img src="{% static 'svgs/ico-home.svg' %}" alt="" aria-hidden="true" class="w-5 h-4 dark:invert">
+      </a>
+    </li>
+    {% for crumb in breadcrumbs %}
+      <li class="flex items-center gap-x-2">
+        {# Разделитель перед пунктом #}<span aria-hidden="true" class="text-slate-400 dark:text-slate-600">/</span>
+        {% if crumb.url and not forloop.last %}
+          {# Обычный пункт со ссылкой (не последний и с заданным url). #}
+          {# Класс не нужен — типовое оформление ссылки (пунктир, цвет, ховер) #}
+          {# задаётся автоматически через css/tailwind-custom.css, @layer base { a {...} }. #}
+          <a href="{{ crumb.url }}">{{ crumb.title }}</a>
+        {% else %}
+          {# Текущая страница: без ссылки, с aria-current="page" для доступности и SEO #}
+          <span aria-current="page" class="font-medium">{{ crumb.title }}</span>
+        {% endif %}
+      </li>
+    {% endfor %}
+  </ol>
+</nav>{% endif %}

lpon_site/templates/block/header.html

@@ -1,11 +1,19 @@
-{% load static %}<header x-data="{scrolled:false}" @scroll.window="scrolled=(window.scrollY>50)" class="sticky top-0 z-50 bg-white/90 dark:bg-slate-800/70 backdrop-blur border-b border-gray-200 dark:border-gray-800 bg-[url({% static 'svgs/cc.svg' %})] bg-bottom-right bg-no-repeat grid grid-cols-[1fr_auto_1fr] items-center  content-center gap-x-4 px-4 py-0">
+{% load static %}<header x-data="{scrolled:false}" @scroll.window="scrolled=(window.scrollY>50)" class="sticky top-0
+   z-50 bg-white/90 dark:bg-slate-800/70 backdrop-blur border-b border-gray-200 dark:border-gray-800
+   bg-[url({% static 'svgs/cc.svg' %})] bg-bottom-right bg-no-repeat grid grid-cols-[1fr_auto_1fr] items-center
+   content-center gap-x-4 px-4 py-0">{% comment %}
+      Пункты меню — ссылки-кнопки, а не типовой текст, поэтому у каждой <a> явно
+      заданы border-0 (отключает пунктирное подчёркивание из общего стиля ссылок) и свой
+      цвет text-slate-900/dark:text-slate-100 (см. пояснение в css/tailwind-custom.css).{% endcomment %}
     {# ЛЕВОЕ МЕНЮ #}<menu class="flex items-center gap-x-4 justify-self-end text-xl font-semibold text-slate-900 dark:text-slate-100">
-    <a href="#" class="px-4 py-2 hover:bg-gray-200 dark:hover:bg-gray-700 rounded-lg">ВИНИЛ</a>
+      <a href="#" class="px-4 py-2 hover:bg-gray-200 dark:hover:bg-gray-700 rounded-lg border-0 text-slate-900 dark:text-slate-100">ВИНИЛ</a>
       <span class="px-4 py-2 bg-gray-300 dark:bg-gray-600 rounded-lg hidden md:block">КАССЕТЫ</span>
-    <a href="#" class="px-4 py-2 hover:bg-gray-200 dark:hover:bg-gray-700 rounded-lg hidden md:block">MD</a>
+      <a href="#" class="px-4 py-2 hover:bg-gray-200 dark:hover:bg-gray-700 rounded-lg hidden md:block border-0 text-slate-900 dark:text-slate-100">MD</a>
     </menu>{# /ЛЕВОЕ МЕНЮ #}
-  {# ЛОГОТИП В ЦЕНТРЕ #}<div class="flex flex-col items-center justify-self-center px-6">
+    {# ЛОГОТИП В ЦЕНТРЕ #}<div class="flex flex-col items-center justify-self-center px-6">{% comment %}
-    <a href="/" class="block leading-none">
+      border-0 — логотип оборачивается в ссылку без текста, отключаем типовое
+      пунктирное подчёркивание ссылки, которое иначе появится под картинкой.{% endcomment %}
+      <a href="/" class="block leading-none border-0">
         <picture id="logo" class="block my-2 leading-none" :class="scrolled?'px-0':'px-6'">
           <source srcset="{% static 'svgs/logo-lpon-d.svg' %}" media="(prefers-color-scheme: dark)" class="mx-auto transition-all duration-300" :class="scrolled?'h-12':'h-18'">
           <img src="{% static 'svgs/logo-lpon-l.svg' %}" alt="Логотип lpon.ru" class="mx-auto block transition-all duration-300" :class="scrolled?'h-12':'h-18'">
@@ -13,9 +21,9 @@
       </a>
     </div>{# /ЛОГОТИП В ЦЕНТРЕ #}
     {# ПРАВОЕ МЕНЮ #}<menu class="flex items-center gap-x-4 justify-self-start text-xl font-semibold text-slate-900 dark:text-slate-100">
-    <a href="#" class="px-4 py-2 hover:bg-gray-200 dark:hover:bg-gray-700 rounded-lg">CD</a>
+      <a href="#" class="px-4 py-2 hover:bg-gray-200 dark:hover:bg-gray-700 rounded-lg border-0 text-slate-900 dark:text-slate-100">CD</a>
-    <a href="#" class="px-4 py-2 hover:bg-gray-200 dark:hover:bg-gray-700 rounded-lg hidden md:block hyphens-none">BLU-RAY</a>
+      <a href="#" class="px-4 py-2 hover:bg-gray-200 dark:hover:bg-gray-700 rounded-lg hidden md:block hyphens-none border-0 text-slate-900 dark:text-slate-100">BLU-RAY</a>
-    <a href="#" class="px-4 py-2 hover:bg-gray-200 dark:hover:bg-gray-700 rounded-lg hidden lg:block">АКСЕССУАРЫ</a>
+      <a href="#" class="px-4 py-2 hover:bg-gray-200 dark:hover:bg-gray-700 rounded-lg hidden lg:block border-0 text-slate-900 dark:text-slate-100">АКСЕССУАРЫ</a>
     </menu>{# /ПРАВОЕ МЕНЮ #}
     {# СЛОГАН #}<p id="slogan" x-show="!scrolled" x-transition:enter="transition ease-out duration-300" x-transition:enter-start="opacity-0" x-transition:enter-end="opacity-100" x-transition:leave="transition ease-in duration-200" x-transition:leave-start="opacity-100" x-transition:leave-end="opacity-0" class="col-span-3 text-xs tracking-widest text-gray-300 bg-black/80 dark:text-gray-300 dark:bg-gray-400/80 px-6 pt-1 pb-1 mb-4 leading-none rounded-lg justify-self-center">Живой звук C-46, C-60, C-90 и&nbsp;далее…</p>{# /СЛОГАН #}
-</header>
+  </header>

lpon_site/templates/catalog.html

@@ -3,6 +3,10 @@
 {% block DESCRIPTION %}LPON — Магазин виниловых пластинок и аудиокассет{% endblock %}
 
 {% block CONTENT %}
+{# Хлебные крошки. Переменная `breadcrumbs` передаётся из вьюхи catalog() #}
+{# (см. lpon_site/frontend/views.py, класс BreadcrumbItem и docstring вьюхи) #}
+{% include "block/breadcrumbs.html" %}
+
 <div class="grid grid-cols-6 gap-4 h-lvh">
   <div class="col-span-4 col-start-2 bg-blue-500 ...">01 Каталог</div>
   <div class="col-start-1 col-end-3 bg-blue-600 ...">02 Блок</div>